# Account settings (/docs/account-settings)







Access your account settings by clicking on "Account" or going to [app.rybbit.io/settings/account](https://app.rybbit.io/settings/account).

<img alt="account settings" src="__img0" />

## Account [#account]

### Name [#name]

Update your display name shown across the platform. This name is visible to other members in your organization.

### Email [#email]

Update your email address for account notifications and login. This is the primary email associated with your account.

### Weekly Email Reports <span className="text-green-500 text-sm">(Cloud)</span> [#weekly-email-reports-cloud]

Enable or disable automatic weekly email reports. When enabled, you'll receive a summary of your analytics performance delivered to your inbox each week.

### Sign Out [#sign-out]

Sign out of your current session.

## Security [#security]

### Change Password [#change-password]

Update your password to keep your account secure.

### Delete Account [#delete-account]

Permanently delete your account and all associated data.

<Callout type="warn">
  This action cannot be undone. If you have an active subscription, you must cancel it before deleting your account.
</Callout>

## API Keys [#api-keys]

Generate API keys to access Rybbit's analytics endpoints from your applications.

### Creating an API Key [#creating-an-api-key]

1. Enter a name for your API key (e.g., "Production App", "Development")
2. Optionally enable **Restrict permissions** to limit the key to specific resources. Leave it off for a full-access key that can do everything you can.
3. Click "Create"
4. Copy and save the generated key immediately

<Callout type="warn">
  On Rybbit Cloud, API keys require a Standard or Pro plan. On a free plan you'll see an upgrade prompt in place of the creation form.
</Callout>

<Callout type="warn">
  API keys are only shown once when created. Store your key securely as you won't be able to view it again.
</Callout>

### Managing API Keys [#managing-api-keys]

Your existing API keys are displayed in a table showing:

* **Name** - The name you assigned to the key
* **Key** - A preview of the key (first few characters)
* **Permissions** - Whether the key has full access or is restricted to specific scopes
* **Created** - When the key was created
* **Last used** - When the key last made a request

You can delete API keys that are no longer needed. Deleting a key immediately revokes access for any applications using it.

### Using API Keys [#using-api-keys]

Include your API key in requests to Rybbit's API endpoints. See the [API documentation](/docs/api) for available endpoints and usage examples.


# Autocapture (/docs/autocapture)



Rybbit can automatically capture common user interactions without requiring any code changes. These features can be enabled in your [Site Settings](/docs/site-settings) under the "Auto Capture" section.

## Available Autocapture Features [#available-autocapture-features]

| Feature           | Description                              | Event Type                    |
| ----------------- | ---------------------------------------- | ----------------------------- |
| Outbound Links    | Track clicks on external links           | `outbound`                    |
| Error Tracking    | Capture JavaScript errors and exceptions | `error`                       |
| Button Clicks     | Track clicks on buttons                  | `button_click`                |
| Copy Events       | Track when users copy text               | `copy`                        |
| Form Interactions | Track form submissions and input changes | `form_submit`, `input_change` |

## Outbound Links [#outbound-links]

When enabled, Rybbit automatically tracks clicks on links that navigate to external domains.

**Tracked properties:**

* `url` - The destination URL
* `text` - The link text
* `target` - The link target attribute (e.g., `_blank`, `_self`)

## Error Tracking [#error-tracking]

Captures uncaught JavaScript errors and unhandled promise rejections from your site. Only errors originating from your domain are tracked (third-party script errors are filtered out).

**Tracked properties:**

* `message` - The error message
* `stack` - Stack trace (truncated to 2000 characters)
* `fileName` - Source file where the error occurred
* `lineNumber` - Line number
* `columnNumber` - Column number

## Button Clicks [#button-clicks]

Automatically tracks clicks on:

* `<button>` elements
* Elements with `role="button"`
* `<input type="submit">` and `<input type="button">`

**Tracked properties:**

* `text` - The button's text content (falls back to `aria-label`, then `value` for input buttons, then `title`)

### Adding Custom Properties [#adding-custom-properties]

You can add custom properties to auto-tracked button clicks using `data-rybbit-prop-*` attributes:

```html
<button
  data-rybbit-prop-category="pricing"
  data-rybbit-prop-variant="blue"
>
  Buy Now
</button>
```

This tracks: `{ text: "Buy Now", category: "pricing", variant: "blue" }`

### Skipping Autocapture for Specific Buttons [#skipping-autocapture-for-specific-buttons]

If you want to track a button with a custom event instead of the automatic `button_click`, add the `data-rybbit-event` attribute:

```html
<!-- This button will fire a custom "signup" event, NOT a button_click -->
<button data-rybbit-event="signup" data-rybbit-prop-plan="pro">
  Sign Up
</button>
```

See [Track Events](/docs/track-events) for more details on custom event tracking.

## Copy Events [#copy-events]

Tracks when users copy text from your site using Ctrl+C, Cmd+C, or the context menu.

**Tracked properties:**

* `text` - The copied text (truncated to 500 characters)
* `textLength` - Original length of the copied text (only included if text was truncated)
* `sourceElement` - The HTML tag where the text was copied from (e.g., `p`, `div`, `span`)

## Form Interactions [#form-interactions]

Tracks two types of form events:

### Form Submissions (`form_submit`) [#form-submissions-form_submit]

Triggered when a form is submitted.

**Tracked properties:**

* `formId` - The form's `id` attribute
* `formName` - The form's `name` attribute
* `formAction` - The form's `action` URL
* `method` - HTTP method (GET, POST, etc.)
* `fieldCount` - Number of form fields
* `ariaLabel` - The form's `aria-label` attribute (if present)

You can add custom properties using `data-rybbit-prop-*` on the form element:

```html
<form
  id="signup"
  data-rybbit-prop-form-type="registration"
  data-rybbit-prop-variant="a"
>
  ...
</form>
```

### Input Changes (`input_change`) [#input-changes-input_change]

Triggered when a user changes the value of an input, select, or textarea field. Disabled inputs are automatically excluded from tracking.

**Tracked properties:**

* `element` - The element type (`input`, `select`, or `textarea`)
* `inputType` - For inputs: the type attribute (e.g., `text`, `email`, `checkbox`)
* `inputName` - The field's `name`, `id`, `aria-label`, or `placeholder` attribute (first available)
* `formId` - The parent form's `id` (if within a form)
* `formName` - The parent form's `name` (if within a form)

You can add custom properties using `data-rybbit-prop-*` on the input element:

```html
<input
  name="email"
  data-rybbit-prop-field-category="contact"
/>

<select
  name="country"
  data-rybbit-prop-section="demographics"
>
  ...
</select>
```

**Privacy note:** Hidden inputs, password fields, and disabled inputs are automatically excluded from tracking.

## Enabling Autocapture [#enabling-autocapture]

1. Go to your site's **Settings**
2. Navigate to the **Auto Capture** section
3. Toggle on the features you want to enable

Changes take effect immediately for new visitors. Existing sessions may need to refresh to pick up the new configuration.

***

**Related Documentation:**

* [Track Events](/docs/track-events) - Manual event tracking
* [Site Settings](/docs/site-settings) - Configure your site
* [Behavior Analytics - Events](/docs/behavior-analytics/events) - View captured events


# Billing (/docs/billing-settings)





Access billing settings by hovering over the sidebar and clicking "Billing".

Subscriptions are scoped to a single organization. If you have multiple organizations, each one requires its own subscription. Switching organizations will show that organization's subscription status.


# Bot detection (/docs/bot-detection)





Rybbit can filter bot traffic before it reaches your normal analytics. When **Block Bot Traffic** is enabled for a site, each incoming tracking request is checked by several detection layers. If any layer identifies the request as bot traffic, the request is excluded from the normal analytics tables and stored separately for bot traffic inspection.

## Enabling Bot Detection [#enabling-bot-detection]

Bot blocking is configured per site:

1. Open your site in the Rybbit dashboard
2. Go to **Site Settings**
3. Enable **Block Bot Traffic**

When this setting is off, Rybbit does not block requests based on bot detection.

## What Happens to Detected Bots [#what-happens-to-detected-bots]

Detected bot requests are not added to your normal analytics data. This keeps dashboard totals, reports, journeys, funnels, session lists, and usage metrics focused on human traffic.

Detected bot visits also do not count toward billable analytics usage. If bot blocking filters a request, you are not charged for that bot visit.

Rybbit still stores a compact bot event record so you can inspect what was filtered. Bot event records include route, device, location, ASN, and which detection layers matched.

## Detection Layers [#detection-layers]

Rybbit runs all detection layers before making a final decision. A request can match multiple layers, and the bot event records every layer that matched.

<Steps>
  <Step>
    ### User-Agent Patterns [#user-agent-patterns]

    The `ua_pattern` layer checks the request user-agent against known bot, crawler, AI agent, SEO tool, monitoring, social preview, framework, and headless browser patterns.

    Examples include:

    * Search engine crawlers
    * Headless browser user-agents
    * AI crawler and agent user-agents
    * SEO and monitoring tools
    * Script or framework HTTP clients
  </Step>

  <Step>
    ### Header Heuristics [#header-heuristics]

    The `header_heuristics` layer scores request headers for browser consistency.

    It looks for signals such as:

    * Missing browser headers
    * Suspicious fetch metadata
    * Inconsistent browser claims
    * Headless or automation-looking headers
    * Stale or unusual Chrome versions
    * Script/framework-style requests that do not look like normal browser traffic

    This layer is useful because many bots use a browser-like user-agent but do not send the full set of headers a real browser normally sends.
  </Step>

  <Step>
    ### Client Signals [#client-signals]

    The `client_signals` layer uses lightweight browser-side signals collected by the tracking script.

    Signals include:

    * Automation APIs
    * Zero or impossible window dimensions
    * Default automation viewport sizes such as `800x600` and `1024x768`
    * Suspicious outer window dimensions
    * Missing browser APIs
    * Missing Chrome globals
    * SwiftShader renderer signals
    * Empty plugin lists

    Rybbit combines these into a weighted score. Strong signals can identify bot traffic on their own, while weaker signals contribute supporting evidence.
  </Step>

  <Step>
    ### ASN and Network Signals [#asn-and-network-signals]

    The `bot_asn` layer uses ASN metadata from the resolved IP address.

    There are two kinds of ASN matches:

    * **Curated bot provider ASNs**: Known AI, scanner, and internet measurement providers can trigger bot detection directly.
    * **Generic hosting/datacenter ASNs**: Hosting ASNs are treated as supporting evidence. They are recorded when another bot layer also matches, but generic hosting ASN alone is not enough to block a request.

    This avoids filtering every legitimate visitor who happens to browse through a cloud, CDN, VPN, corporate gateway, or first-party proxy, while still preserving ASN context when other bot evidence exists.
  </Step>

  <Step>
    ### Rate and Anomaly Detection [#rate-and-anomaly-detection]

    The `rate_anomaly` layer watches for bursty or crawl-shaped behavior.

    It tracks short rolling windows for patterns such as:

    * Too many events from the same IP and user-agent
    * Too many events from the same IP
    * Too many distinct paths visited quickly
    * Too many different user-agents from one IP
    * Too many hostnames from one IP
    * High site-wide volume from one user-agent
    * Large volumes of requests missing client-side bot scores

    This layer is designed to catch fast crawlers, floods, and replayed tracking requests that may not have obvious user-agent or browser fingerprint signals.
  </Step>
</Steps>

## Bot Identity [#bot-identity]

Every detected bot carries the layers that caught it. Bots matched by one of Rybbit's curated user-agent patterns carry three more fields, which is what the Bots dashboard groups by:

| Field          | Example       | Meaning                                      |
| -------------- | ------------- | -------------------------------------------- |
| `bot_name`     | `GPTBot`      | The name the bot publishes in its user agent |
| `bot_operator` | `OpenAI`      | Who runs it                                  |
| `bot_purpose`  | `ai_training` | What the fetch is for                        |

A bot matched only by a broad pattern (`crawl`, `spider`) is still filtered, but has no published identity — those rows read as **Unnamed**, which is more useful than a guess.

### Purposes [#purposes]

`bot_purpose` answers a different question from `bot_category`. Category groups bots into families; purpose says what the operator does with the page, which is the distinction that matters for AI traffic:

| Purpose          | What it means                                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ai_training`    | Collecting pages to train a model. Sends no readers back. Examples: GPTBot, ClaudeBot, CCBot, Google-Extended, Bytespider                                       |
| `ai_search`      | Indexing pages so an assistant can cite them. Can send readers back. Examples: OAI-SearchBot, Claude-SearchBot, PerplexityBot                                   |
| `ai_agent`       | A person asked an assistant to open the page, and it fetched it there and then. Examples: ChatGPT-User, Claude-User, Perplexity-User, Google-Agent, Claude Code |
| `search`         | Classic search engine indexing                                                                                                                                  |
| `social_preview` | Link unfurling                                                                                                                                                  |
| `seo`            | Backlink, rank, and site-audit crawlers                                                                                                                         |
| `monitoring`     | Uptime, synthetic, and performance checks                                                                                                                       |
| `security`       | Scanners                                                                                                                                                        |
| `scripted`       | HTTP libraries and CLI clients                                                                                                                                  |
| `headless`       | Browser automation                                                                                                                                              |

Splitting the AI family in three is the point: a training crawler reading 4,000 pages and a person's assistant opening one page are both `category: ai`, but they mean opposite things for your site.

<Callout>
  These fields were added in a later release. Bot events recorded before then have empty identity fields and appear as **Unnamed** / **Unclassified**; nothing is backfilled.
</Callout>

## How Decisions Are Made [#how-decisions-are-made]

Rybbit does not stop at the first matching layer. It runs every layer, records all matches, and then makes one final decision.

A request is marked as bot traffic when at least one blocking layer matches. The resulting bot event includes boolean fields for each layer:

* User-agent pattern
* Header heuristics
* Client signals
* Bot ASN
* Rate anomaly

Because multiple layers can match the same request, per-layer bot counts can add up to more than the total number of bot requests.

## Server-Side Tracking [#server-side-tracking]

Requests sent to `/api/track` with `Authorization: Bearer <api key>` and a valid API key are treated as trusted server-side ingestion. Four of the five layers are skipped: the headers, the client signals, the network address, and the request rate all belong to your server, not to the visitor it is reporting, so scoring them would convict your own backend.

The user-agent layer still runs, on the `user_agent` you send. Nothing changes for ordinary backend events — a request reporting a real browser's user agent is tracked normally.

### Reporting crawlers that never run JavaScript [#reporting-crawlers-that-never-run-javascript]

Rybbit's tracker is JavaScript, so a crawler that fetches your HTML and executes nothing never reaches Rybbit at all. Most AI training crawlers work exactly that way, which is why the Bots dashboard carries a note about its own coverage.

If you want to see them, report them from the edge — middleware, a worker, or a reverse proxy — forwarding the real request's `user_agent`:

```json
{
  "site_id": "1",
  "hostname": "example.com",
  "pathname": "/pricing",
  "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.2; +https://openai.com/gptbot"
}
```

A forwarded crawler user agent is classified and lands in your bot events with full identity, rather than in your analytics as a phantom visitor.

<Callout type="warn">
  Do not expose API keys in browser JavaScript. API keys are only for server-side requests.
</Callout>

## Proxies and CDN Setups [#proxies-and-cdn-setups]

If you proxy Rybbit through Cloudflare Workers, AWS CloudFront, Nginx, Caddy, or another reverse proxy, forward the original visitor IP:

```txt
X-Forwarded-For: <visitor-ip>
X-Real-IP: <visitor-ip>
```

Also preserve the original `User-Agent`, `Referer`, and `Accept-Language` headers where possible.

If the proxy IP is sent instead of the visitor IP, traffic may be geolocated to the proxy location and may inherit the proxy provider's ASN.

See the [proxy troubleshooting guide](/docs/proxy-guide/troubleshooting) for examples.

## What Bot Detection Does Not Guarantee [#what-bot-detection-does-not-guarantee]

Bot detection improves analytics quality, but no bot filter is perfect.

Some sophisticated bots can look like normal browsers. Some legitimate users may browse through unusual network paths or constrained browser environments. Rybbit uses multiple layers to reduce both misses and false positives, but you should still interpret bot counts as an operational signal rather than an exact measurement of all automation on your site.


# Comparison (/docs/comparison)





| Feature                           | Rybbit                                                             | GA4                                                                | Plausible                                                            | Cloudflare                                                         |
| --------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Open Source**                   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Self-Hosting**                  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />\* | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Cookieless & Privacy friendly** | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Advanced Maps**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Advanced Filters**              | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Limited</span>    | <span className="inline-flex items-center gap-1">Limited</span>      | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Web Vitals**                    | <span className="inline-flex items-center gap-1">Paid</span>       | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Session Details**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **User Profiles**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Session Replays**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Funnels**                       | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Paid</span>         | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **User Journeys**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Retention Analysis**            | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Goals & Events**                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Real-time Dashboard**           | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Custom Events (JSON)**          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Limited</span>      | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Error Tracking**                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Public Dashboards**             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Organizations**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Frog 🐸**                       | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |

\* Plausible's Community Edition has very limited features compared to their cloud version


# Data Import (/docs/data-import)





The data import feature allows you to migrate your historical analytics data from other platforms to Rybbit. This preserves your analytics history when switching from competitors, giving you a complete view of your data without losing valuable insights.

## Supported Platforms [#supported-platforms]

Currently, Rybbit supports importing data from:

* Umami
* Simple Analytics
* Plausible

Additional platforms may be added in the future based on user demand.

<Callout type="info">
  Umami and Simple Analytics are imported from a CSV export, while Plausible is imported from its ZIP export. The Import dialog automatically expects the correct file type for the platform you select.
</Callout>

## Plan Requirements [#plan-requirements]

### Cloud Version [#cloud-version]

| Plan     | Access          | Historical Window   | Monthly Event Limit |
| -------- | --------------- | ------------------- | ------------------- |
| Free     | ❌ Not available | -                   | -                   |
| Standard | ✅ Available     | 36 months (3 years) | Plan limit applies  |
| Pro      | ✅ Available     | 60 months (5 years) | Plan limit applies  |

### Self-Hosted Version [#self-hosted-version]

Self-hosted installations have **unlimited** access to data imports with no restrictions on:

* Historical data window (import data from any date)
* Event quotas (no monthly limits)
* Concurrent imports (no limit on active imports)

## Import Limits [#import-limits]

### Historical Data Windows [#historical-data-windows]

The historical data window determines how far back you can import data:

* **Standard plans**: Import data from the past 36 months (3 years)
* **Pro plans**: Import data from the past 60 months (5 years)
* **Self-hosted**: Unlimited - import data from any date

Events outside your plan's historical window will be automatically skipped during import.

### Event Quotas [#event-quotas]

Imported events count toward your monthly event limit:

* If you're close to your monthly limit, imports may be partially skipped
* Skipped events are counted and displayed in the import history
* Consider upgrading your plan if you need to import large amounts of data

### Concurrent Imports [#concurrent-imports]

For cloud users:

* **Maximum 1 active import per organization**
* New imports are blocked until the current one completes
* Maximum 2-hour timeout per import

Self-hosted users have no concurrent import restrictions.

## How to Import Data [#how-to-import-data]

<Steps>
  <Step>
    ### Export Data from Source Platform [#export-data-from-source-platform]

    **Umami:**

    1. Navigate to Settings → Data
    2. Export your data as CSV
    3. Ensure the export includes all required fields

    **Simple Analytics:**

    1. Go to your site settings
    2. Navigate to Export section
    3. Download your analytics data as CSV

    **Plausible:**

    1. Open your site's dashboard
    2. Use the CSV export option to download your data
    3. Keep the exported **ZIP** archive as-is — do not unzip it
  </Step>

  <Step>
    ### Navigate to Import Settings [#navigate-to-import-settings]

    1. Open your Rybbit dashboard
    2. Navigate to Site Settings
    3. Click on the **Import** tab
  </Step>

  <Step>
    ### Select Platform and Upload File [#select-platform-and-upload-file]

    1. Select your source platform from the dropdown
    2. Click "Choose File" and select your exported file (a **CSV** for Umami and Simple Analytics, or a **ZIP** for Plausible)
    3. Click the **Import** button

    <Callout type="warn">
      For very large imports (multiple GB), consider splitting your CSV into smaller files and importing them sequentially.
    </Callout>
  </Step>

  <Step>
    ### Monitor Import Progress [#monitor-import-progress]

    Your import will begin processing in the background. You can:

    * View the import status in the "Import History" section
    * Monitor the number of imported, skipped, and invalid events
    * Continue using Rybbit while the import runs

    <Callout type="info">
      Large imports may take several minutes to complete. The page will automatically refresh to show updated progress.
    </Callout>
  </Step>
</Steps>

## Import History [#import-history]

The Import History section displays all your past and current imports.

### Import Metrics [#import-metrics]

Each import shows three key metrics:

**Imported Events**

* Number of events successfully imported into Rybbit
* These events are now visible in your analytics dashboard

**Skipped Events**

* Events that were excluded during import
* Common reasons:
  * Outside your plan's historical data window
  * Would exceed your monthly event quota

**Invalid Events**

* Events that failed validation during import
* Common reasons:
  * Malformed CSV data
  * Missing required fields
  * Invalid date/time formats
  * Data type mismatches

<Callout type="warn">
  If you see a high number of invalid events, verify your CSV export matches the expected format for your platform.
</Callout>

### Managing Imports [#managing-imports]

**Deleting Completed Imports**

* Click the trash icon next to any completed import
* Confirm the deletion in the dialog
* This will permanently remove the import record **and all associated events** from your analytics
* Active imports cannot be deleted

<Callout type="error">
  Deleting an import removes all events that were imported. This action cannot be undone. Make sure you have a backup of your original CSV file.
</Callout>

## Troubleshooting [#troubleshooting]

### Events Skipped Due to Quota Limits [#events-skipped-due-to-quota-limits]

**Cause:** Importing the events would exceed your monthly event limit.

**Solution:**

* Wait until the next billing cycle when your quota resets
* Upgrade to a plan with a higher event limit
* Import smaller date ranges to stay within quota

### Events Skipped Due to Date Range [#events-skipped-due-to-date-range]

**Cause:** Events are older than your plan's historical data window.

**Solution:**

* Upgrade to Pro plan for 60-month history (vs 24-month on Standard)
* For self-hosted, no action needed - all dates are allowed
* Filter your CSV export to only include recent data

### High Invalid Event Count [#high-invalid-event-count]

**Cause:** CSV format doesn't match the expected structure for your platform.

**Solution:**

1. Verify you selected the correct platform
2. Check that your CSV export includes all required fields
3. Look for special characters or malformed data in the CSV
4. Try importing a small sample file (first 100 rows) to test

### Import Appears Stuck [#import-appears-stuck]

**Cause:** Very large files can take time to process, or a timeout occurred.

**Solution:**

* Wait up to 2 hours for the import to complete
* If still stuck after 2 hours, the import will be automatically marked as complete
* Check the imported event count to see if any data was processed
* Contact support if no events were imported

## Best Practices [#best-practices]

### Before You Import [#before-you-import]

1. **Export a complete backup** from your current analytics platform
2. **Test with a small sample** (first 1,000 rows) before importing your full dataset
3. **Check your event quota** to ensure you have sufficient capacity
4. **Verify date ranges** match your plan's historical window
5. **Review CSV format** matches the required structure for your platform

### During Import [#during-import]

1. **Don't close the browser tab**
2. **Monitor the progress** in the Import History section
3. **Check for skipped/invalid events** early to catch format issues
4. **Wait for completion** before starting another import (cloud users)

### After Import [#after-import]

1. **Verify your data** appears correctly in analytics dashboards
2. **Check date ranges** to ensure historical data is visible
3. **Compare totals** with your source platform to validate accuracy
4. **Keep the original CSV** as a backup before deleting the import


# Definitions (/docs/definitions)



## Aggregate Metrics [#aggregate-metrics]

### Unique Users [#unique-users]

The total number of distinct individuals who visited your website, identified by a unique user ID. Each user is counted only once regardless of how many times they visit.

### Sessions [#sessions]

A series of user interactions with your website within a given time frame. A session ends after 30 minutes of inactivity from the same user ID. Multiple pageviews can occur within one session.

### Pageviews [#pageviews]

The total number of times visitors have viewed pages on your website. Each time a page is loaded or reloaded counts as a pageview.

### Pages Per Session [#pages-per-session]

The average number of pages viewed during a session. Calculated by dividing the total number of pageviews by the total number of sessions.

### Bounce Rate [#bounce-rate]

The percentage of sessions where a user leaves your site after viewing only one page without any interaction. A high bounce rate might indicate that landing pages aren't relevant to visitors.

### Session Duration [#session-duration]

The average length of time users spend on your site during a session. Longer sessions typically indicate more engaged visitors.

## Individual Datapoints [#individual-datapoints]

### User ID [#user-id]

A unique identifier generated from a hash of the visitor's IP address and browser user-agent. This anonymized ID helps track unique visitors without storing personally identifiable information.

### Hostname [#hostname]

The domain name of the website being visited (e.g., example.com).

### Pathname [#pathname]

The path portion of the URL that follows the hostname (e.g., /blog/article).

### Entry Page [#entry-page]

The first page viewed by a user during a session. Identifies which pages commonly serve as entry points to your site.

### Exit Page [#exit-page]

The last page viewed by a user before ending their session. Helps identify where users tend to leave your site.

### Querystring [#querystring]

The portion of a URL that follows a question mark, containing parameters (e.g., ?utm\_source=newsletter).

### Page Title [#page-title]

The title of the webpage as defined in the HTML `<title>` tag.

### Referrer [#referrer]

The URL that a user was on before coming to your site. Shows how users are discovering your content.

### UTM Source [#utm-source]

Identifies which website, search engine, or other source is sending traffic to your site (e.g., google, newsletter, twitter).

### UTM Medium [#utm-medium]

Identifies the marketing medium (e.g., cpc, email, social).

### UTM Term [#utm-term]

Identifies paid search keywords. Used primarily for paid search campaigns.

### UTM Campaign [#utm-campaign]

Identifies the specific campaign or promotion that brought users to your site.

### UTM Content [#utm-content]

Identifies what specifically was clicked to bring the visitor to your site (e.g., banner ad, text link).

### Channel [#channel]

A categorization of traffic sources into standard groups such as direct, search, social, email, or referral.

### Browser [#browser]

The web browser used by the visitor (e.g., Chrome, Firefox, Safari).

### Browser Version [#browser-version]

The specific version of the browser being used.

### Operating System [#operating-system]

The operating system used by the visitor (e.g., Windows, macOS, iOS, Android).

### Operating System Version [#operating-system-version]

The specific version of the operating system being used.

### Language [#language]

The preferred language setting of the visitor's browser.

### Country [#country]

The country where the user is located, based on IP geolocation.

### Region [#region]

The state or region where the user is located, based on IP geolocation.

### City [#city]

The city where the user is located, based on IP geolocation.

### Latitude [#latitude]

The geographic latitude coordinate of the user's approximate location.

### Longitude [#longitude]

The geographic longitude coordinate of the user's approximate location.

### Screen Width [#screen-width]

The width of the visitor's screen or device viewport in pixels.

### Screen Height [#screen-height]

The height of the visitor's screen or device viewport in pixels.

### Device Type [#device-type]

The type of device being used (e.g., desktop, tablet, mobile).

### Event Name [#event-name]

The name of a custom event triggered by user interaction (e.g., "button\_click", "form\_submit").

### Event Properties [#event-properties]

Additional contextual data associated with custom events, stored as key-value pairs. Used to provide more detail about specific interactions.


# Embeds (/docs/embed-widget)



Rybbit supports two iframe embed options:

* [Widget Embeds](/docs/embeds/widget) show a compact live visitor widget on any web page.
* [Dashboard Embed](/docs/embeds/dashboard) shows your analytics dashboard in an iframe.

Both embeds are self-contained iframes. There is no script tag, no JavaScript on your site, and no dependency on the Rybbit tracking script.

## Which Embed Should I Use? [#which-embed-should-i-use]

Use [Widget Embeds](/docs/embeds/widget) when you want a small live visitor count, chart, or top-countries summary. Widget Embeds do not make your dashboard public.

Use [Dashboard Embed](/docs/embeds/dashboard) when you want to publish the full read-only analytics dashboard. Dashboard Embed uses a generated private link, so Public Analytics is not required.


# Experiments (/docs/experiments)





Experiments are A/B tests built on top of Rybbit. Each experiment splits your visitors across the variants of a [multivariate feature flag](/docs/feature-flags), then measures how often each variant completes a [conversion goal](/docs/goals). Rybbit calculates the conversion rate for every variant, the **lift** relative to your control, and how confident you can be that the difference is real.

<Callout type="info">
  An experiment ties together two features you may already use: a **multivariate feature flag** decides which variant each visitor sees, and a **goal** defines the conversion you are optimizing for. If you understand those two pieces, you understand experiments.
</Callout>

## How Experiments Work [#how-experiments-work]

An experiment has three moving parts:

| Part           | What it does                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assignment** | A multivariate feature flag assigns each visitor to one stable variant (for example `control` or `variant_a`) based on its rollout percentages.                                                   |
| **Exposure**   | When your code reads the flag with `rybbit.flag()`, Rybbit records an exposure for that variant. The number of distinct sessions exposed to a variant is the denominator for its conversion rate. |
| **Conversion** | The experiment's primary goal — a page visit or a custom event — counts as a conversion for whichever variant the visitor was assigned.                                                           |

Because assignment is sticky for a given visitor, a person sees the same variant on repeat visits, which keeps your results consistent.

## Creating an Experiment [#creating-an-experiment]

Open your site in the Rybbit dashboard, go to **Experiments**, and click **New experiment**. A guided wizard walks you through each step.

<Steps>
  <Step>
    ### Basics [#basics]

    Give the experiment a **name** and, optionally, a **hypothesis** and **description*&#x2A;. The hypothesis is internal context for your team — something like &#x2A;"Changing the CTA copy will increase signups."* It does not affect assignment or tracking.

    New experiments are created as **drafts** so you can add the implementation code before any traffic is split.
  </Step>

  <Step>
    ### Assignment [#assignment]

    Choose how visitors are split into variants:

    * **Create a new flag** — Define a new multivariate flag with its own variants and rollout split. Each variant needs a unique key, and the rollout percentages must add up to &#x2A;*100%**.
    * **Use an existing flag** — Pick a multivariate flag that is not already attached to another experiment.

    <Callout type="info">
      Each experiment uses its own multivariate flag. The flag's variant keys (such as `control` and `variant_a`) are what you branch on in code.
    </Callout>
  </Step>

  <Step>
    ### Goal [#goal]

    Pick the conversion you want to compare variants against:

    * **Create a new goal** — Define a **page goal** (a URL path such as `/signup/complete`) or an **event goal** (a custom event such as `signup_completed`). The form provides autocomplete suggestions based on paths and events already seen on your site.
    * **Use an existing goal** — Connect a goal you already track.
    * **Skip for now** — Create the experiment without a goal and add one later. Conversion results require a goal.
  </Step>

  <Step>
    ### Review and Implement [#review-and-implement]

    Review the assignment flag and goal, then create the experiment. Rybbit creates any new flag or goal you configured, connects them, and shows you the **implementation code** for the flag. The experiment stays in **draft** until you start it from the experiment list.
  </Step>
</Steps>

## Implementing in Code [#implementing-in-code]

Read the experiment's flag in your app and branch your UI or behavior on the returned variant. Reading the flag also records the exposure that powers your results, so make sure it runs wherever the tested experience is shown.

<Tabs items="['JavaScript', 'TypeScript']">
  <Tab value="JavaScript">
    ```javascript
    window.rybbit.onReady((rybbit) => {
      const variant = rybbit.flag("checkout_cta", "control");

      if (variant === "variant_a") {
        // Render the variant experience.
      } else {
        // Render the control experience.
      }
    });
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript
    type ExperimentVariant = "control" | "variant_a";

    window.rybbit.onReady((rybbit) => {
      const variant = rybbit.flag("checkout_cta", "control") as ExperimentVariant;

      switch (variant) {
        case "variant_a":
          // Render the variant experience.
          break;
        default:
          // Render the control experience.
          break;
      }
    });
    ```
  </Tab>
</Tabs>

If your primary goal is an **event goal**, fire that event when the conversion action happens:

```javascript
window.rybbit.onReady((rybbit) => {
  rybbit.event("signup_completed");
});
```

**Page goals** need no extra code — Rybbit counts sessions that reach the goal's path automatically.

<Callout type="info">
  Use a stable variant for the `rybbit.flag()` fallback (usually `"control"`) so visitors still get a sensible experience before the flag resolves or if the experiment is paused.
</Callout>

## Reading Results [#reading-results]

Each experiment shows a results panel comparing every variant. Results respect the global date range and filters applied on the page.

| Metric              | Description                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Variant**         | The variant key, with the **Control** marked as the baseline.                                                         |
| **Sessions**        | Sessions exposed to that variant, alongside the number that converted.                                                |
| **Conversion rate** | Conversions divided by the number of exposed sessions (the **Sessions** figure) for that variant.                     |
| **Lift**            | The percentage change in conversion rate relative to the control. Positive lift is shown in green, negative in red.   |
| **Confidence**      | How confident Rybbit is that the variant's difference from the control is real, based on a two-proportion comparison. |

Rybbit summarizes the state of each experiment at a glance:

* **Gathering data** — Not enough exposures or conversions yet to draw a conclusion.
* **Leading** — A variant is outperforming the control with at least **95% confidence**.
* **Winner** — The variant recorded as the winner once the experiment is decided.

<Callout type="warn">
  Avoid stopping an experiment the moment a variant looks ahead. Let it run until it reaches 95% confidence with a meaningful number of conversions, otherwise early noise can masquerade as a real difference.
</Callout>

## Experiment Lifecycle [#experiment-lifecycle]

Experiments move through four statuses, which you control from the experiment list:

| Status        | Meaning                                                                                 |
| ------------- | --------------------------------------------------------------------------------------- |
| **Draft**     | Created but not yet collecting results. Add your implementation code here.              |
| **Running**   | Actively splitting traffic and recording exposures and conversions.                     |
| **Paused**    | Temporarily stopped. Visitors keep their existing assignments.                          |
| **Completed** | Finished. Use this once you have a result and have shipped (or rolled back) the change. |

Use **Start**, **Pause**, and **Complete** on each experiment to move between states.

## Best Practices [#best-practices]

* Change one thing at a time so you can attribute any lift to a single difference.
* Make sure your variant rollout percentages add up to 100% unless you intentionally want unassigned traffic.
* Read the flag wherever the tested experience renders so every exposed visitor is counted.
* Pick a primary goal that directly reflects the outcome you care about, not a proxy metric.
* Wait for 95% confidence and a healthy sample size before declaring a winner.
* After completing an experiment, ship the winning variant and remove the flag branch to keep your code clean.

***

**Related Documentation:**

* [Feature Flags](/docs/feature-flags) — The assignment mechanism behind experiments
* [Goals](/docs/goals) — Define the conversion an experiment measures
* [Track Events](/docs/track-events) — Fire custom events for event goals
* [Tracking Script](/docs/script) — Load the script and use `onReady()`


# Feature Flags (/docs/feature-flags)





Feature flags let you change product behavior without deploying new code. In Rybbit, a flag can be evaluated in the browser, on your server, or in both places. Flag assignments are also attached to analytics events so you can filter and compare behavior by flag value.

<Callout type="info">
  Feature flags are different from [tags](/docs/tagging). Tags label traffic that you already routed yourself. Feature flags decide which value a visitor receives at runtime.
</Callout>

## Create a Flag [#create-a-flag]

1. Open your site in the Rybbit dashboard.
2. Go to **Feature Flags**.
3. Click **New flag**.
4. Choose a stable **key**, such as `new_checkout` or `pricing_banner`.
5. Select the flag type, runtime, and targeting conditions.
6. Enable the flag when you are ready for it to evaluate as active.

The **key** is the public identifier used in code. Treat it as the flag name and avoid changing it after the flag is in use.

## Flag Types [#flag-types]

| Type                  | Returns                                         | Best for                                                                  |
| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
| **Boolean**           | `true` or `false`                               | Releasing a feature on/off, gradual rollouts, allowlists                  |
| **Multiple variants** | A variant key like `"control"` or `"variant_a"` | Comparing more than one experience or configuration                       |
| **Remote config**     | `true` plus a payload from `flagPayload()`      | Shipping structured config such as copy, colors, limits, or JSON settings |

### Boolean Flags [#boolean-flags]

Boolean flags support a rollout percentage for each condition set. If the visitor matches the condition set and falls inside the rollout bucket, `window.rybbit.flag()` returns `true`.

```javascript
window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);

  if (enabled) {
    showNewCheckout();
  }
});
```

### Multiple Variants [#multiple-variants]

Multiple variant flags return the selected variant key. Each variant has its own rollout percentage and optional payload.

```javascript
window.rybbit.onReady((rybbit) => {
  const variant = rybbit.flag("homepage_cta", "control");

  if (variant === "variant_a") {
    renderAlternateCTA();
  }
});
```

Variant rollout percentages are evaluated in order. If the visitor falls outside the total allocated percentage, the flag returns `false`.

### Remote Config [#remote-config]

Remote config flags are useful when you want Rybbit to choose a JSON payload. For remote config, `flag()` returns whether a config matched, and `flagPayload()` returns the actual config.

```javascript
window.rybbit.onReady((rybbit) => {
  const config = rybbit.flagPayload("checkout_config", {
    buttonText: "Continue",
    theme: "default",
  });

  renderCheckout(config);
});
```

Remote config can still use targeting. This lets you serve one config to beta users, another config to a country, and a default config to everyone else.

## Runtime [#runtime]

Each flag has a runtime:

| Runtime    | Evaluated by                 | Use when                                                       |
| ---------- | ---------------------------- | -------------------------------------------------------------- |
| **Client** | The browser tracking script  | UI changes, frontend copy, client-only experiments             |
| **Server** | Your backend through the API | Backend behavior, pricing logic, data access, anything private |
| **Both**   | Browser and server           | Both sides need the same decision                              |

<Callout type="warn">
  Do not put secrets in client or both-runtime flag payloads. Browser-evaluated flags and payloads are visible to the user.
</Callout>

## Targeting and Condition Sets [#targeting-and-condition-sets]

Flags use ordered condition sets. Each set contains targeting rules plus the rollout, variants, or payload for users who match that set.

Evaluation works like this:

1. Rybbit checks condition sets from top to bottom.
2. The first condition set whose rules all match is selected.
3. Rybbit applies the rollout, variant allocation, or remote config payload from that selected set.
4. Later condition sets are not evaluated.

This means condition set order matters. Put narrow segments first and broad defaults last.

<Callout type="warn">
  If a visitor matches a boolean condition set but falls outside that set's rollout percentage, Rybbit returns `false` and does not continue to later condition sets.
</Callout>

### Targeting Fields [#targeting-fields]

| Field           | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| Hostname        | Current hostname, such as `example.com`                          |
| Pathname        | Current path, such as `/pricing`                                 |
| Query parameter | A specific URL query parameter                                   |
| Referrer        | The document referrer                                            |
| Language        | Browser language, such as `en-US`                                |
| Country         | Visitor country resolved from IP                                 |
| Region          | Visitor region resolved from IP                                  |
| City            | Visitor city resolved from IP                                    |
| Device type     | Device category derived from user agent and screen size          |
| User ID         | The identified user ID, falling back to the anonymous visitor ID |
| User trait      | A trait set through `identify()` or `setTraits()`                |

### Operators [#operators]

Targeting rules support:

* `equals`
* `not_equals`
* `contains`
* `starts_with`
* `ends_with`
* `regex`

All rules in a condition set must match. Multiple condition sets act as ordered alternatives.

## Browser Runtime [#browser-runtime]

The tracking script automatically evaluates client and both-runtime flags when it loads. It sends context such as anonymous visitor ID, identified user ID, URL, referrer, language, screen size, IP-derived location, and saved user traits.

Use `onReady()` before reading flags if you need the evaluated value during page initialization:

```javascript
window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);
  const payload = rybbit.flagPayload("new_checkout", {});
});
```

Available browser methods:

<TypeTable
  type="{
  &#x22;flag(key, fallback)&#x22;: {
    description: &#x22;Returns a single flag value. Reading a flag also records a feature flag exposure event once per flag value/version.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flagPayload(key, fallback)&#x22;: {
    description: &#x22;Returns the payload for a flag or variant. Use this for remote config and multivariate payloads.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flags()&#x22;: {
    description: &#x22;Returns all evaluated flag values keyed by flag key.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flagPayloads()&#x22;: {
    description: &#x22;Returns all available flag payloads keyed by flag key.&#x22;,
    type: &#x22;function&#x22;,
  },
}"
/>

Assignments are included on analytics events as a feature flag map. This lets you filter dashboard reports by flag key and value.

### Identify and Traits [#identify-and-traits]

If you call `identify()` or `setTraits()`, the browser runtime refreshes feature flags using the updated user context.

```javascript
window.rybbit.identify("user_123", {
  plan: "pro",
  beta: true,
});
```

You can then target flags using **User ID** or **User trait** rules.

## Server Runtime [#server-runtime]

Use server runtime for decisions that should not happen in the browser. The server endpoint returns server and both-runtime flags only.

```
POST /api/sites/:siteId/feature-flags/evaluate
```

### Request [#request]

<TypeTable
  type="{
  anonymousId: {
    description: &#x22;Stable anonymous visitor ID used for rollout bucketing. Keep this stable for sticky assignments.&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  identifiedUserId: {
    description: &#x22;Logged-in user ID. Enables user ID rules and loads saved user traits.&#x22;,
    type: &#x22;string&#x22;,
  },
  hostname: {
    description: &#x22;Hostname used by hostname targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  pathname: {
    description: &#x22;Path used by pathname targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  query: {
    description: &#x22;Parsed query parameter object used by query targeting rules.&#x22;,
    type: &#x22;Record<string, string>&#x22;,
  },
  querystring: {
    description: &#x22;Raw query string. Used if query is not provided.&#x22;,
    type: &#x22;string&#x22;,
  },
  referrer: {
    description: &#x22;Referrer used by referrer targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  language: {
    description: &#x22;Language code used by language targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  screenWidth: {
    description: &#x22;Screen width used with user agent parsing to derive device type.&#x22;,
    type: &#x22;number&#x22;,
  },
  screenHeight: {
    description: &#x22;Screen height used with user agent parsing to derive device type.&#x22;,
    type: &#x22;number&#x22;,
  },
}"
/>

<Tabs items="['cURL', 'JavaScript']">
  <Tab value="cURL">
    ```bash
    curl -X POST "https://app.rybbit.io/api/sites/123/feature-flags/evaluate" \
      -H "Authorization: Bearer rb_your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "anonymousId": "visitor_abc",
        "identifiedUserId": "user_123",
        "hostname": "example.com",
        "pathname": "/checkout",
        "query": { "plan": "pro" },
        "language": "en-US",
        "screenWidth": 1440,
        "screenHeight": 900
      }'
    ```
  </Tab>

  <Tab value="JavaScript">
    ```javascript
    const response = await fetch(
      "https://app.rybbit.io/api/sites/123/feature-flags/evaluate",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer rb_your_api_key_here",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          anonymousId: "visitor_abc",
          identifiedUserId: "user_123",
          hostname: "example.com",
          pathname: "/checkout",
          query: { plan: "pro" },
          language: "en-US",
          screenWidth: 1440,
          screenHeight: 900,
        }),
      }
    );

    const data = await response.json();
    const newCheckout = data.flags.new_checkout?.value === true;
    ```
  </Tab>
</Tabs>

### Response [#response]

```json
{
  "flags": {
    "new_checkout": {
      "key": "new_checkout",
      "value": true,
      "flagType": "boolean",
      "payload": { "copy": "Try it now" },
      "conditionSet": "Default",
      "version": 3,
      "reason": "rollout",
      "matched": true,
      "rolloutPercentage": 100
    }
  },
  "generatedAt": "2026-05-27T12:00:00.000Z"
}
```

Assignment fields:

| Field               | Description                                                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`             | The evaluated flag value. Boolean flags return `true` or `false`; multiple variant flags return a variant key or `false`; remote config returns `true` when matched. |
| `payload`           | Optional payload from the selected condition set or selected variant.                                                                                                |
| `variant`           | Selected variant key for multiple variant flags.                                                                                                                     |
| `conditionSet`      | Name of the condition set that matched.                                                                                                                              |
| `reason`            | Why the assignment was produced, such as `rollout`, `variant`, `remote_config`, `fallthrough`, `target_mismatch`, or `disabled`.                                     |
| `matched`           | Whether the flag produced an active match.                                                                                                                           |
| `rolloutPercentage` | The rollout percentage that was evaluated.                                                                                                                           |
| `version`           | Flag version. Increments when the flag is edited.                                                                                                                    |

## Analytics and Filtering [#analytics-and-filtering]

Feature flag assignments are stored on events. Browser-tracked events include evaluated client flags automatically. Server-side events can include a `feature_flags` object in the [HTTP API](/docs/api/sending-events) payload:

```json
{
  "site_id": "123",
  "type": "custom_event",
  "event_name": "purchase",
  "pathname": "/checkout",
  "feature_flags": {
    "new_checkout": "true",
    "homepage_cta": "variant_a"
  }
}
```

Use feature flag filters in the dashboard to compare behavior between flag values.

## Best Practices [#best-practices]

* Keep flag keys stable and descriptive, such as `new_checkout` or `pricing_page_copy`.
* Use **Client** runtime only for values that are safe to expose in the browser.
* Use **Server** runtime for permission checks, pricing logic, and private backend behavior.
* Put specific condition sets before broad default condition sets.
* Keep remote config payloads small and JSON-serializable.
* Use a stable `anonymousId` for server-side evaluation so rollout assignments remain sticky.
* Remove stale flags after rollout is complete to keep your dashboard and codebase clean.

**Related Documentation:**

* [Tracking Script](/docs/script)
* [Identify Users](/docs/identify-users)
* [Tagging](/docs/tagging)
* [API - Sending Events](/docs/api/sending-events)


# Filter traffic (/docs/filter-traffic)





Rybbit provides server-side traffic filtering to keep unwanted data out of your analytics. You can exclude your own traffic, staging and preview environments, internal tools, monitoring checks, or entire countries.

Filters are configured from **Site Settings → Exclusions**.

## Available Filters [#available-filters]

| Filter                    | Use it for                                                            | Matching behavior                                         | Limit       |
| ------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- | ----------- |
| **IP Exclusions**         | Your home, office, VPN, or internal network traffic                   | Single IPs, CIDR ranges, and IPv4 ranges                  | 100 entries |
| **Country Exclusions**    | Regional filtering or compliance requirements                         | Two-letter ISO country codes, such as `US`, `GB`, or `DE` | 250 entries |
| **Path Exclusions**       | Admin pages, private pages, preview routes, or test pages             | Case-insensitive glob patterns using `*`                  | 100 entries |
| **Hostname Exclusions**   | Localhost, staging domains, preview deployments, or temporary domains | Case-insensitive glob patterns using `*`                  | 100 entries |
| **User Agent Exclusions** | Monitoring tools, headless browsers, or custom crawlers               | Case-insensitive substring matching                       | 100 entries |

When a request matches an exclusion, Rybbit returns a successful response but does not write the event to analytics storage.

## IP Exclusions [#ip-exclusions]

Block traffic from specific IP addresses or ranges at the server level. This is usually the best way to hide your own traffic.

Supported formats:

* **Single IPv4**: `192.168.1.1`
* **Single IPv6**: `2001:db8::1`
* **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`
* **IPv4 ranges**: `192.168.1.1-192.168.1.10`

For setup instructions and best practices, see [Hiding Your Own Traffic](/docs/hiding-own-traffic).

## Country Exclusions [#country-exclusions]

Block all traffic geolocated to specific countries. Rybbit resolves the visitor IP address with the MaxMind GeoLite2 database, then compares the resulting country code to your exclusion list.

Use two-letter ISO country codes:

* `US` for United States
* `GB` for United Kingdom
* `CN` for China
* `DE` for Germany

Country codes are stored as uppercase values in the dashboard and API.

<Callout type="warning">
  **Private IP addresses**: Country exclusion cannot work for private IP addresses such as `127.0.0.1`, `192.168.x.x`, `10.x.x.x`, or `172.16.x.x` because they cannot be geolocated. This includes localhost and Docker container IPs during local development.
</Callout>

<Callout type="info">
  **VPNs and proxies**: Visitors using VPNs or proxies are detected based on the VPN or proxy server location, not their physical location.
</Callout>

## Path Exclusions [#path-exclusions]

Exclude traffic to specific page paths. Path exclusions match the pathname only, not the query string.

Examples:

```txt
/admin/*
/preview
/internal/*
```

Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `/admin/*` matches `/admin/users` and `/admin/settings`.

Use path exclusions for pages that should not appear in analytics at all, such as admin dashboards, internal previews, or test routes.

<Callout type="info">
  For client-side-only pageview skipping, you can also use the tracking script's `data-skip-patterns` option. Site-level path exclusions are enforced on the server and also apply to session replay ingestion.
</Callout>

## Hostname Exclusions [#hostname-exclusions]

Exclude traffic from specific hostnames. This is useful when the same site ID is used across production, staging, preview, and local environments.

Examples:

```txt
localhost
staging.example.com
*.vercel.app
*.netlify.app
```

Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `*.vercel.app` matches `my-preview.vercel.app` but not `vercel.app`.

## User Agent Exclusions [#user-agent-exclusions]

Exclude traffic from requests whose user agent contains a configured substring.

Examples:

```txt
HeadlessChrome
MyMonitor
Pingdom
```

Matching is case-insensitive and uses substring matching, so `HeadlessChrome` matches `Mozilla/5.0 HeadlessChrome/120`.

Use user-agent exclusions for uptime monitors, synthetic checks, internal crawlers, or other tools with predictable user-agent strings.

## What Filters Apply To [#what-filters-apply-to]

Traffic filters run before normal analytics data is stored. They apply to:

* Pageviews
* Custom events
* Performance and Web Vitals events
* Error events
* Autocapture events
* Session replay batches

## How Filters Are Evaluated [#how-filters-are-evaluated]

Rybbit checks exclusions in this order:

1. IP address
2. Country
3. Path
4. Hostname
5. User agent

If any filter matches, the event is accepted with a `200` response but is not tracked. Changes usually take effect within 60 seconds because site configuration is cached briefly on the server.

## Testing Filters Locally [#testing-filters-locally]

To test country filtering locally, send a public IP through the `X-Real-IP` header:

```bash
curl -X POST http://localhost:3001/api/track \
  -H "Content-Type: application/json" \
  -H "X-Real-IP: 8.8.8.8" \
  -d '{
    "type": "pageview",
    "site_id": "your-site-id",
    "hostname": "example.com",
    "pathname": "/test"
  }'
```

For path and hostname filters, set `pathname` and `hostname` in the event payload to values that should match your configured exclusions.


# Funnels (/docs/funnels)













<img alt="Funnels Dashboard" src="__img0" />

Funnels let you define a sequence of steps — page visits, custom events, or autocaptured interactions — and measure how many users progress through each stage. You can see where users convert, where they drop off, and drill into the sessions at each step to understand why.

## Creating a Funnel [#creating-a-funnel]

<img alt="Creating a Funnel" src="__img1" />

<Steps>
  <Step>
    ### Click "Create Funnel" [#click-create-funnel]

    Each funnel has:

    * **Name** — A label for the funnel (e.g., "Signup Flow", "Checkout Process")
    * **Steps** — Two or more sequential steps, each tracking a page visit, custom event, outbound link, button click, form submission, or copy event
  </Step>

  <Step>
    ### Add Steps [#add-steps]

    A funnel always must have at least two steps.

    There are six types of funnel steps. Path and custom event steps require a value. For the four autocaptured interaction types, the pattern is optional—leave it empty to match every interaction of that type.

    <Tabs items="['Path', 'Custom Event', 'Outbound Link', 'Button Click', 'Form Submit', 'Copy']">
      <Tab value="Path">
        Path steps match pageview events by URL path.

        * Enter a URL path starting with `/`
        * Wildcards are supported:
          * `*` matches a single path segment — `/products/*` matches `/products/shoes`
          * `**` matches multiple segments — `/docs/**` matches `/docs/api/v2/intro`
      </Tab>

      <Tab value="Custom Event">
        Custom event steps match events by name (e.g., `add_to_cart`, `purchase_completed`).

        Events must be tracked using the Rybbit tracking script. See [Track Events](/docs/track-events) for setup instructions.
      </Tab>

      <Tab value="Outbound Link">
        Outbound link steps match clicks on links that lead away from your site.

        * Enter a destination URL pattern such as `https://example.com/pricing` or `https://*.example.com/**`
        * Leave the pattern empty to match any outbound click

        Outbound link tracking is enabled by default.
      </Tab>

      <Tab value="Button Click">
        Button click steps match clicks on buttons, button/submit inputs, and elements with `role="button"`.

        * Enter a visible button-text pattern such as `Sign Up` or `Start * Trial`
        * Leave the pattern empty to match any button click

        Buttons that already use `data-rybbit-event` are recorded as custom events instead.
      </Tab>

      <Tab value="Form Submit">
        Form submit steps match submissions of HTML forms.

        * Enter a form name or ID pattern such as `signup-form`
        * The pattern can also match the form's action URL
        * Leave the pattern empty to match any form submission
      </Tab>

      <Tab value="Copy">
        Copy steps match text that visitors copy from your site.

        * Enter a copied-text pattern such as `PROMO*`
        * Leave the pattern empty to match any copied text
      </Tab>
    </Tabs>

    Autocaptured interaction patterns support wildcards: `*` matches one or more characters and `**` also matches an empty value. The form suggests values already observed on your site.

    <Callout type="info" title="Enable autocapture first">
      Button click, form interaction, and copy tracking are disabled by default. Enable the event types you want to use in the **Tracking** tab of your site settings. Only interactions collected after tracking is enabled can appear in a funnel. See [Autocapture](/docs/autocapture) for the properties collected with each type.
    </Callout>
  </Step>

  <Step>
    ### Configure Step Options (optional) [#configure-step-options-optional]

        <img alt="Step Options" src="__img2" />

    Each step has additional configuration options:

    * **Label** (optional) — A friendly display name for the step
    * **Hostname** (optional) — Restrict matching to a specific domain, useful for multi-domain sites
    * **Property Filters** (optional) — Filter by URL parameters (for path steps) or event properties (for all other step types). Multiple filters can be added per step, and all must match.
  </Step>
</Steps>

## Reading Funnel Results [#reading-funnel-results]

The funnel visualization updates in real time as you configure steps. For each step, you'll see:

* **Sessions** — How many sessions reached this step
* **Conversion Rate** — Percentage of the first step's sessions that reached this step
* **Dropped** — How many sessions completed the previous step but not this one
* **Dropoff Rate** — Percentage of the previous step's sessions lost at this point

The horizontal bar for each step shows two layers:

* **Solid bar** — Overall conversion from the first step
* **Striped overlay** — Conversion from the immediately previous step

Steps are evaluated sequentially — each step must occur after the previous one within the same session.

## Viewing Sessions [#viewing-sessions]

<img alt="Viewing Sessions" src="__img3" />

Click any step to expand it and view the sessions associated with that step:

* **Reached** tab — Sessions that completed this step
* **Dropped Off** tab — Sessions that reached the previous step but didn't make it to this one (available for step 2 and beyond)

Each session shows entry/exit pages, duration, location, device info, referrer, UTM parameters, and user ID if identified. Sessions are paginated.

***

**Related Documentation:**

* [Autocapture](/docs/autocapture) — Configure automatically captured interactions
* [Goals](/docs/goals) — Track single-action conversions
* [Track Events](/docs/track-events) — Set up custom event tracking


# Goals (/docs/goals)













<img alt="Goals Dashboard" src="__img0" />

Goals let you define specific actions — from visiting a page to clicking a button — and measure how often your visitors complete them. Each goal tracks a conversion rate against total sessions, giving you a clear picture of how effectively your site drives key outcomes.

## Creating a Goal [#creating-a-goal]

<img alt="Creating a Goal" src="__img1" />

<Steps>
  <Step>
    ### Click "Create Goal" [#click-create-goal]

    Every goal has:

    * **Name** (optional) — A friendly label like "Completed Checkout" or "Signed Up"
    * **Type** — Page, custom event, outbound link, button click, form submission, or copied text
    * **Value** — A required path or custom event name, or an optional pattern that narrows an autocaptured interaction
  </Step>

  <Step>
    ### Choose a Goal Type [#choose-a-goal-type]

    There are six goal types. Page and custom event goals require a value. For the four autocaptured interaction types, the pattern is optional—leave it empty to count every interaction of that type.

    <Tabs items="['Page', 'Custom Event', 'Outbound Link', 'Button Click', 'Form Submit', 'Copy']">
      <Tab value="Page">
        Page goals track when a user visits a URL matching a given path pattern.

        * The value must be a path starting with `/` (not a full URL)
        * Wildcards are supported:
          * `*` matches a single path segment — `/blog/*` matches `/blog/my-post`
          * `**` matches multiple segments — `/docs/**` matches `/docs/api/v2/intro`

        The form provides autocomplete suggestions based on actual paths seen on your site.
      </Tab>

      <Tab value="Custom Event">
        Custom event goals track when an event with a specific name is fired. The value is the event name (e.g., `signup_clicked`, `purchase_completed`).

        Events must be tracked using the Rybbit tracking script. See [Track Events](/docs/track-events) for setup instructions.
      </Tab>

      <Tab value="Outbound Link">
        Outbound link goals track clicks on links that lead away from your site.

        * Enter a destination URL pattern such as `https://example.com/pricing` or `https://*.example.com/**`
        * Leave the pattern empty to count clicks to any external URL

        Outbound link tracking is enabled by default.
      </Tab>

      <Tab value="Button Click">
        Button click goals track clicks on buttons, button/submit inputs, and elements with `role="button"`.

        * Enter a visible button-text pattern such as `Sign Up` or `Start * Trial`
        * Leave the pattern empty to count any button click

        Buttons that already use `data-rybbit-event` are recorded as custom events instead.
      </Tab>

      <Tab value="Form Submit">
        Form submit goals track submissions of HTML forms.

        * Enter a form name or ID pattern such as `signup-form`
        * The pattern can also match the form's action URL
        * Leave the pattern empty to count any form submission
      </Tab>

      <Tab value="Copy">
        Copy goals track text that visitors copy from your site.

        * Enter a copied-text pattern such as `PROMO*`
        * Leave the pattern empty to count any copied text
      </Tab>
    </Tabs>

    Autocaptured interaction patterns support wildcards: `*` matches one or more characters and `**` also matches an empty value. The form suggests values already observed on your site.

    <Callout type="info" title="Enable autocapture first">
      Button click, form interaction, and copy tracking are disabled by default. Enable the event types you want to use in the **Tracking** tab of your site settings. Only interactions collected after tracking is enabled can count toward a goal. See [Autocapture](/docs/autocapture) for the properties collected with each type.
    </Callout>
  </Step>

  <Step>
    ### Add Property Filters (optional) [#add-property-filters-optional]

        <img alt="Property Filters" src="__img2" />

    You can narrow a goal to only count conversions when specific properties match:

    * **Page goals** — Filter by URL parameters (e.g., only count visits where `utm_source=adwords`)
    * **Custom event goals** — Filter by event properties (e.g., only count events where `plan=premium`)
    * **Autocaptured interaction goals** — Filter by captured properties such as `url`, `text`, `formName`, `formId`, or `formAction`

    Toggle **Match specific URL parameters** or **Match specific event properties** to add filters. You can add multiple filters per goal — all filters must match for a session to count as a conversion.
  </Step>
</Steps>

## Goal Metrics [#goal-metrics]

Each goal card displays:

* **Total Conversions** — The number of distinct sessions that completed the goal
* **Conversion Rate** — Conversions divided by total sessions in the selected time period, shown as a percentage with a visual progress bar

Goals respect the global date range and filters (country, device, browser, etc.) applied on the page.

## Viewing Converted Sessions [#viewing-converted-sessions]

<img alt="Viewing Converted Sessions" src="__img3" />

Click a goal card to expand it and see the sessions that converted. Each session shows:

* Entry and exit pages
* Session duration
* Location (country, region, city)
* Device, browser, and OS
* Referrer, channel, and UTM parameters
* User ID (if identified)

Sessions are sorted by most recent first and paginated.

***

**Related Documentation:**

* [Autocapture](/docs/autocapture) — Configure automatically captured interactions
* [Track Events](/docs/track-events) — Set up custom event tracking
* [Funnels](/docs/funnels) — Analyze multi-step conversion paths


# Hiding your own traffic (/docs/hiding-own-traffic)





There are several ways to disable Rybbit tracking to hide your own visits from analytics.

<Tabs items="['IP Exclusion', 'Browser Extensions', 'localStorage Method']">
  <Tab>
    **IP Exclusion (Recommended)**: Block traffic from specific IP addresses or ranges at the server level for complete accuracy.

    ### Setting Up IP Exclusion [#setting-up-ip-exclusion]

    1. **Navigate to Site Settings**: Go to your site's settings page in the Rybbit dashboard
    2. **Find IP Exclusions section**: Scroll down to the "IP Exclusions" configuration
    3. **Add your IP addresses**: Enter the IP addresses or ranges you want to exclude

    ### Supported IP Formats [#supported-ip-formats]

    Rybbit supports multiple IP exclusion formats:

    * **Single IPv4**: `192.168.1.1`
    * **Single IPv6**: `2001:db8::1`, `::1`
    * **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`
    * **IPv4 ranges**: `192.168.1.1-192.168.1.10` (IPv4 only)

    ### Examples [#examples]

    ```
    # Your home IP address
    203.0.113.45

    # Your office network (CIDR)
    203.0.113.0/24

    # IP range for your team
    198.51.100.10-198.51.100.20

    # IPv6 address
    2001:db8::1
    ```

    ### Key Features [#key-features]

    * **Server-side filtering**: Traffic is blocked before it reaches your analytics, providing highly accurate exclusion
    * **Multiple formats**: Supports individual IPs, CIDR notation, and ranges
    * **IPv4 and IPv6**: Full support for both IP versions
    * **Near real-time updates**: Changes take effect within seconds
    * **No browser dependency**: Works regardless of browser or device

    <Callout type="info">
      **IP Stability Note**: IP addresses can change due to factors like mobile networks, VPN usage, ISP changes, and IPv6 privacy extensions. You may need to periodically update your excluded IPs to maintain effective filtering.
    </Callout>

    <Callout type="info">
      **Dynamic IP Addresses**: If you frequently use VPNs, mobile networks, or have a dynamic IP address that changes regularly, consider these approaches:

      * Use CIDR ranges that cover your typical IP pool (consult your ISP or VPN provider)
      * Combine IP exclusion with browser extensions for comprehensive coverage
      * Check your current IP periodically and update exclusions as needed
      * For corporate networks, exclude the entire office IP range rather than individual addresses
    </Callout>

    <Callout type="warning">
      **Note**: IPv6 range notation (e.g., `2001:db8::1-2001:db8::ff`) is not supported. Use CIDR notation instead (e.g., `2001:db8::/32`).
    </Callout>

    <Callout type="info">
      **Finding your IP**: You can find your current IP address by visiting sites like [whatismyipaddress.com](https://whatismyipaddress.com) or [ipinfo.io](https://ipinfo.io).
    </Callout>
  </Tab>

  <Tab>
    **Browser Extensions**: Easy client-side solution using community-maintained browser extensions.

    ### Available Extensions [#available-extensions]

    * **[Chrome Extension](https://chrome.google.com/webstore/detail/gofnfdfidbkpellionhpmkejgaajieoo)**: Install from the Chrome Web Store
    * **[Firefox Extension](https://addons.mozilla.org/en-US/firefox/addon/rybbit-opt-out/)**: Install from Firefox Add-ons

    These extensions automatically disable Rybbit tracking on all websites where you have Rybbit installed, without requiring any manual configuration.

    <Callout type="info">
      **Self-hosted users**: These extensions require Rybbit version 1.1.0 or higher. If you're running an older version, please update your installation or use the localStorage method.
    </Callout>

    *These extensions are community-maintained by [@davidfiala](https://github.com/davidfiala).*
  </Tab>

  <Tab>
    **localStorage Method**: Manual configuration using your browser's developer console for more granular control.

    <Steps>
      ### 1. Open your browser's developer console [#1-open-your-browsers-developer-console]

      Press **F12** or right-click the page and select "Inspect"

      Navigate to the "Console" tab

      ### 2. Disable tracking [#2-disable-tracking]

      Enter this command to disable tracking:

      ```js
      localStorage.setItem('disable-rybbit', 'true');
      ```

      ### 3. Re-enable tracking (when needed) [#3-re-enable-tracking-when-needed]

      If you want to re-enable tracking later, enter:

      ```js
      localStorage.removeItem('disable-rybbit');
      ```
    </Steps>
  </Tab>
</Tabs>

## Summary [#summary]

Multiple methods are available for hiding your own traffic, each with different advantages:

* **IP exclusion** provides the most accurate solution by blocking traffic at the server level, working regardless of browser or device
* **Browser extensions** offer convenience by automatically working across all your Rybbit-enabled websites
* **localStorage method** gives granular control for specific websites or temporary disabling

For most users, **IP exclusion is recommended** as it provides highly accurate filtering for all devices accessing your site from the excluded IP addresses. The other methods work at the browser level and may be useful for additional flexibility or temporary exclusions.


# Identify Users (/docs/identify-users)





<Callout type="warn" title="GDPR & Privacy Compliance">
  User identification involves processing personal data. Before using these features, ensure you have a lawful basis for processing (typically user consent), have disclosed tracking in your privacy policy, and provide users the ability to access and delete their data. Only collect traits you have explicit consent to process.
</Callout>

Rybbit allows you to identify logged-in users and associate their activity with a persistent identity across devices and sessions. This enables powerful user-level analytics, including tracking user journeys, understanding retention, and personalizing experiences.

<img alt="identify users" src="__img0" />

## How It Works [#how-it-works]

By default, Rybbit assigns an anonymous ID to each visitor based on their device fingerprint. When you call `identify()`, you link this anonymous visitor to a known user ID, allowing you to:

* Track the same user across multiple devices
* Associate pre-login activity with the logged-in user
* Store user metadata (traits) like email, name, and custom fields
* View identified users in your dashboard with their real names

When a new alias is created (i.e., the first time `identify()` is called for a given device), Rybbit retroactively updates all past anonymous events from that device to include the identified user ID. This means pre-login pageviews and events are attributed to the user once they identify themselves.

## Special Trait Fields [#special-trait-fields]

When identifying users, certain trait fields are treated specially by Rybbit:

| Field      | Description                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| `username` | **Primary display name** - Shown in the users list and session cards instead of the user ID |
| `name`     | **Fallback display name** - Used if username is not provided                                |
| `email`    | Displayed below the user's name in the dashboard                                            |

You can also include any custom fields you need for segmentation and analysis.

## Limits [#limits]

* **Traits size**: Maximum 2KB per identify call. Traits are stored as JSON, so keep payloads concise.
* **User ID length**: Maximum 255 characters.

## API Reference [#api-reference]

### `window.rybbit.identify(userId, traits?)` [#windowrybbitidentifyuserid-traits]

Sets a custom user ID for tracking logged-in users across devices and sessions, with optional user traits (metadata).

* `userId` (String): The unique identifier for the user. This will be stored in localStorage and persist across browser sessions. &#x2A;*Note: Custom user IDs are stored exactly as provided without any hashing or modification.**
* `traits` (Object, Optional): An object containing user metadata like email, name, username, or any custom fields. This data is stored in Rybbit and can be used to identify users in the dashboard. Setting a trait to `null` removes it from the user's profile.

```javascript
// Identify a user when they log in (without traits)
window.rybbit.identify("user_12345");

// Identify a user with traits (recommended)
window.rybbit.identify("user_12345", {
  username: "johndoe",           // Primary display name
  name: "John Doe",              // Fallback display name
  email: "john@example.com",
  plan: "premium",
  company: "Acme Inc"
});

// All subsequent events and pageviews will be associated with this user ID
```

### `window.rybbit.setTraits(traits)` [#windowrybbitsettraitstraits]

Updates the traits for the currently identified user without re-identifying them. Useful for updating user properties after initial identification.

* `traits` (Object): An object containing user metadata. New traits are merged with existing traits. &#x2A;*Setting a trait to `null` removes it from the user's profile.**

```javascript
// Update user traits after they upgrade their plan
window.rybbit.setTraits({
  plan: "enterprise",
  upgraded_at: "2024-01-15"
});

// Remove a trait by setting it to null
window.rybbit.setTraits({
  temporary_flag: null  // This trait will be removed
});
```

**Note:** You must call `identify()` before using `setTraits()`. If no user is identified, this will log a warning.

### `window.rybbit.clearUserId()` [#windowrybbitclearuserid]

Clears the stored user ID. Useful when a user logs out.

```javascript
// Clear user identification when user logs out
window.rybbit.clearUserId();
```

### `window.rybbit.getUserId()` [#windowrybbitgetuserid]

Returns the currently set user ID, or `null` if none is set.

```javascript
// Check if a user is identified
const currentUserId = window.rybbit.getUserId();
if (currentUserId) {
  console.log('Current user:', currentUserId);
} else {
  console.log('No user identified');
}
```

## Important Notes [#important-notes]

* **Unique user counts**: Every user count in the dashboard — Unique Users, the users chart, the Users table, traits, and retention — keys on the custom user ID wherever one is present, falling back to the anonymous fingerprint only for visitors who have never identified. Two people sharing an IP address and browser count as two users, and one person on a laptop and a phone counts as one. Sites that never call `identify()` are unaffected. Because the count follows the IDs you pass, sending a fresh ID per visit (rather than a stable per-person ID) will inflate it.
* **Identified sessions**: When a custom user ID is present, session assignment includes both the anonymous device fingerprint and the custom user ID. Different identified users therefore remain in separate sessions even when they share the same IP address and user agent.
* **Shared devices**: If multiple users log in from the same device (same IP address and user agent), calling `identify()` with a new user ID updates the alias to point to the new user. Future events will be attributed to the most recently identified user. Past events that were already backfilled retain their original attribution.
* **Cross-device tracking**: Identifying the same user on different devices creates separate aliases. Events from each device are linked to the user independently via the `identified_user_id` field.
* **Retroactive backfill**: The backfill runs asynchronously when a new alias is first created. ClickHouse mutations may take a short time to propagate depending on table size. Subsequent `identify()` calls from the same device (even with a different user ID) do not re-backfill old events.
* **`clearUserId()` behavior**: Calling `clearUserId()` removes the user ID from localStorage so future events are anonymous. It does not delete the alias in the database or modify previously attributed events.

## Complete Example [#complete-example]

Here's a typical workflow for user identification:

```javascript
// When user logs in
function handleLogin(userData) {
  // Set user identification with traits
  window.rybbit.identify(userData.id, {
    username: userData.username,
    name: userData.fullName,
    email: userData.email,
    plan: userData.plan
  });

  // Track login event
  window.rybbit.event("User Login", {
    method: "email"
  });
}

// When user upgrades their plan
function handlePlanUpgrade(newPlan) {
  // Update traits without re-identifying
  window.rybbit.setTraits({
    plan: newPlan,
    upgraded_at: new Date().toISOString()
  });

  // Track upgrade event
  window.rybbit.event("Plan Upgraded", {
    new_plan: newPlan
  });
}

// When user logs out
function handleLogout() {
  // Track logout event
  window.rybbit.event("User Logout");

  // Clear user identification
  window.rybbit.clearUserId();
}

// Check identification status
function checkUserStatus() {
  const userId = window.rybbit.getUserId();
  if (userId) {
    console.log("User is identified:", userId);
  } else {
    console.log("Anonymous user");
  }
}
```

**Related Documentation:**

* [Track Events](/docs/track-events)
* [Behavior Analytics - Users Tab](/docs/behavior-analytics/users)
* [API - Sending Events](/docs/api/sending-events)


# Introduction (/docs)



**Rybbit** is a powerful open source web and product analytics platform. Check out our [live demo](https://demo.rybbit.com/81) using a real production site.

<DocsHomeCards />

## Getting Started [#getting-started]

Choose the option that's right for you:

* **Cloud Version:** Sign up for the [hosted version](https://app.rybbit.io/signup). Get up and running in minutes.
* **Self-Host:** Follow our [self hosting guide](/docs/self-hosting) to set up Rybbit on your own server.

And then learn how to add the [tracking script](/docs/script) to your website to start collecting data.

## Code [#code]

Rybbit is open sourced under the AGPL-3.0 license. You can find the code on [GitHub](https://github.com/rybbit-io/rybbit).

## Community [#community]

Join our [Discord server](https://discord.gg/DEhGb4hYBj) or talk to me on [X](https://x.com/yang_frog). I'm always looking for feedback and ideas to make Rybbit as awesome as possible.


# Inviting users (/docs/inviting-users)





<Callout type="info">
  On self-hosted instances, this workflow is slightly different. Instead of inviting users, you can create a new user and set their password directly since self-hosted instances don't send emails.
</Callout>

<Steps>
  <Step>
    ### Add the user to your organization [#add-the-user-to-your-organization]

    Go to **Settings > Organization** and click the "Invite Member" button. Enter the user's email address.
  </Step>

  <Step>
    ### Select the user's role [#select-the-users-role]

    You can assign the user one of three roles:

    **Owners** have full access to all features including billing, organization deletion, and member management.

    **Admins** can manage members and access all sites, but cannot delete the organization or manage billing.

    **Members** can view analytics for assigned sites only. They cannot manage settings or other members.

    #### Restricting site access for members [#restricting-site-access-for-members]

    When inviting a member, you can optionally restrict their access to specific sites. Check the "Restrict access to specific sites" option and select which sites the member should be able to view.

    If you don't enable this option, the member will have access to all sites in your organization.

    <Callout type="info">
      Site access restrictions only apply to members. Admins and owners always have full access to all sites.
    </Callout>
  </Step>

  <Step>
    ### Assign teams (optional) [#assign-teams-optional]

    If your organization has [teams](/docs/teams) set up, you can assign the new member to a team during the invitation. When the member accepts the invitation, they will automatically be added to the selected team.

    This is useful for ensuring new members immediately have access to the right group of sites without needing to configure access separately.
  </Step>

  <Step>
    ### Send the invite [#send-the-invite]

    Click the "Invite" button. The user will receive an email with a link to sign up for Rybbit. You can manage all pending invitations in the Organization settings page.
  </Step>
</Steps>

## Managing site access for existing members [#managing-site-access-for-existing-members]

You can change a member's site access at any time after they've joined your organization.

1. Go to **Settings > Organization**
2. Find the member in the list and click the edit (pencil) icon in the Actions column for that member
3. Toggle "Restrict access to specific sites" and select the sites they should have access to
4. Click "Save changes"

The member will immediately only see the sites you've selected. If you disable the restriction, they'll regain access to all sites.

<Callout type="info">
  Currently, each user can only be in one organization.
</Callout>


# Localhost tracking (/docs/localhost-tracking)





Rybbit does not restrict tracking to your registered domain — the tracking script works from `localhost` (or any other origin) out of the box. As long as your snippet has a valid `data-site-id`, events sent during local development are recorded like any other traffic.

```html
<script
  defer
  src="https://app.rybbit.io/api/script.js"
  data-site-id="YOUR_SITE_ID">
</script>
```

<Callout type="warning">
  Because localhost traffic is tracked by default, the usual problem is the opposite one: development visits polluting your production analytics. Use one of the approaches below to keep your data clean.
</Callout>

## Keeping development traffic out of production data [#keeping-development-traffic-out-of-production-data]

### Option 1: Use a separate development site [#option-1-use-a-separate-development-site]

Create a second site in your Rybbit dashboard (e.g. "My App (dev)") and use its site ID during development. Your production site's data stays untouched, and you can still verify events end-to-end.

```jsx
// Next.js example
export function Analytics() {
  const siteId =
    process.env.NODE_ENV === 'development'
      ? process.env.NEXT_PUBLIC_RYBBIT_DEV_SITE_ID
      : process.env.NEXT_PUBLIC_RYBBIT_SITE_ID;

  return (
    <script
      defer
      src="https://app.rybbit.io/api/script.js"
      data-site-id={siteId}
    />
  );
}
```

### Option 2: Only load the script in production [#option-2-only-load-the-script-in-production]

If you don't need analytics while developing, skip loading the script entirely outside production:

```jsx
// Next.js example
export function Analytics() {
  if (process.env.NODE_ENV !== 'production') return null;

  return (
    <script
      defer
      src="https://app.rybbit.io/api/script.js"
      data-site-id={process.env.NEXT_PUBLIC_RYBBIT_SITE_ID}
    />
  );
}
```

```javascript
// Vanilla JS example
if (process.env.NODE_ENV === 'production') {
  const script = document.createElement('script');
  script.defer = true;
  script.src = 'https://app.rybbit.io/api/script.js';
  script.setAttribute('data-site-id', 'YOUR_SITE_ID');
  document.head.appendChild(script);
}
```

### Option 3: Filter the traffic instead [#option-3-filter-the-traffic-instead]

If you want the script loaded everywhere but excluded from your stats, use your site's exclusion settings — see [Filtering Traffic](/docs/filter-traffic) and [Hiding Your Own Traffic](/docs/hiding-own-traffic).

## Troubleshooting [#troubleshooting]

**Events not showing up from localhost?**

* Confirm `data-site-id` matches the site you're looking at in the dashboard
* Check the browser console for errors and the Network tab for `POST` requests to `/api/track`
* Disable ad blockers or privacy extensions — they commonly block analytics scripts on any origin, including localhost
* Make sure the page isn't excluded by your site's IP, path, or user-agent exclusion rules


# Managing your installation (/docs/managing-your-installation)





## Helpful scripts [#helpful-scripts]

<Callout>
  You probably need to run `chmod +x *.sh` before running the scripts.
</Callout>

### Updating Your Installation [#updating-your-installation]

Rybbit is updated frequently with new features and bug fixes. You can update your installation by running the following commands:

**update.sh**: Update to the latest version by pulling new code and rebuilding containers

```bash
git pull
./update.sh
```

### Restarting Your Installation [#restarting-your-installation]

**restart.sh**: Restart all services (useful when you've changed .env settings)

```bash
./restart.sh
```

## Docker Compose Commands [#docker-compose-commands]

You can also manage services directly with Docker Compose:

* **Stop all services**:
  ```bash
  docker compose stop
  ```

* **Stop and remove containers** (preserves data):
  ```bash
  docker compose down
  ```

* **Start services** (if you used setup.sh with default webserver):
  ```bash
  docker compose --profile with-webserver up -d
  ```

* **Start services** (if you used setup.sh with --no-webserver):
  ```bash
  docker compose up -d
  ```

* **View logs**:
  ```bash
  docker compose logs -f
  ```

<Callout>
  If you are using your self-hosted Rybbit without anyone else, you can disable new user signups by setting `DISABLE_SIGNUP=true` in the `.env` file at the root of the repository.
</Callout>

## Database Access [#database-access]

You can access the databases by running the following commands:

* **Access Clickhouse**:
  ```bash
  docker exec -it clickhouse clickhouse-client --database analytics
  ```

* **Access Postgres**:
  ```bash
  docker exec -it postgres psql -U frog -d analytics
  ```

### Edit Session Replay Retention Policy [#edit-session-replay-retention-policy]

The default session replay retention policy is 30 days. This may be too long for some users as session replays can take up a lot of space. You can edit it by running the following command:

```bash
docker exec -it clickhouse clickhouse-client --database analytics
ALTER TABLE session_replay_events MODIFY TTL toDateTime(timestamp) + INTERVAL 14 DAY;
ALTER TABLE session_replay_metadata MODIFY TTL start_time + INTERVAL 14 DAY;
```

## Anonymous Usage Telemetry [#anonymous-usage-telemetry]

To help us improve Rybbit, self-hosted instances automatically send anonymous usage statistics to our cloud service. This includes:

* Number of rows in a few core ClickHouse tables (events and the session replay tables)
* Total database size
* Your Rybbit version
* A hashed instance identifier

No personal data, website content, or visitor information is ever collected.

<Callout type="info">
  You can completely disable telemetry by adding `DISABLE_TELEMETRY=true` to your `.env` file and restarting your services.
</Callout>


# Organization settings (/docs/organization-settings)







Access organization settings by clicking on "Organization" or going to [app.rybbit.io/settings/organization](https://app.rybbit.io/settings/organization).

<img alt="organization settings" src="__img0" />

## Organization [#organization]

### Organization Name [#organization-name]

Update your organization's display name. Only the organization owner can change this setting.

### Delete Organization [#delete-organization]

Permanently delete the organization and all associated data including sites, analytics, reports, and member associations.

<Callout type="warn">
  This action cannot be undone. You must type the organization name to confirm deletion. If you have an active subscription, you must cancel it before deleting the organization.
</Callout>

## Members [#members]

View and manage all members in your organization. The members table shows:

* **Name** - Member's display name
* **Email** - Member's email address
* **Role** - Owner, Admin, or Member
* **Site Access** - Which sites the member can access
* **Joined** - When they joined the organization

### Member Roles [#member-roles]

| Role       | Permissions                                                                               |
| ---------- | ----------------------------------------------------------------------------------------- |
| **Owner**  | Full access to all features, can manage members, billing, and delete the organization     |
| **Admin**  | Can manage members and access all sites, cannot delete the organization or manage billing |
| **Member** | Can view analytics for assigned sites only, cannot manage settings or other members       |

### Inviting Members [#inviting-members]

Owners can invite new members or create user accounts. See the [Inviting Users](/docs/inviting-users) guide for detailed instructions.

### Teams [#teams]

You can organize sites into teams to control which members have access to which sites. See the [Teams](/docs/teams) guide for details.


# Roadmap (/docs/roadmap)



Rybbit is a quickly growing project. We already have quite a few features, but there is much more to come.

## Planned features [#planned-features]

* Data import from Google Analytics, PostHog, and more
* More tracking script/SDK integration guides
* Custom themes

Once again, join our [Discord server](https://discord.gg/DEhGb4hYBj) or follow me on [X](https://x.com/yang_frog) to share your feedback and ideas. We would love to hear from you!


# Troubleshooting (/docs/script-troubleshooting)





If you've installed the Rybbit tracking script but aren't seeing any traffic in your dashboard, this guide will help you diagnose and fix common issues.

## Check if the Script is Loaded [#check-if-the-script-is-loaded]

The first step is to verify that the Rybbit script is properly loaded on your page.

<Steps>
  <Step>
    ### Open Your Browser's Developer Console [#open-your-browsers-developer-console]

    Right-click anywhere on your webpage and select **Inspect** (or **Inspect Element**). Then click on the **Console** tab at the top of the panel that opens.

    Alternatively, you can use keyboard shortcuts:

    * **Windows/Linux**: Press `Ctrl + Shift + J` or `F12`
    * **Mac**: Press `Cmd + Option + J`
  </Step>

  <Step>
    ### Type "rybbit" and Press Enter [#type-rybbit-and-press-enter]

    In the console, type `rybbit` and press Enter.

    **If the script is loaded correctly**, you'll see an object with functions like this:

    ```javascript
    {event: ƒ, pageview: ƒ, identify: ƒ, setTraits: ƒ, clearUserId: ƒ, …}
    ```

    **If the script is NOT loaded**, you'll see an error like:

    ```
    Uncaught ReferenceError: rybbit is not defined
    ```

    If you see the error, the script is not loading properly. Continue reading for common causes.
  </Step>
</Steps>

## Common Issues [#common-issues]

### Data Attributes Being Stripped [#data-attributes-being-stripped]

Some platforms, content management systems, tag managers, and "delay JavaScript" optimizers automatically remove or sanitize `data-*` attributes from script tags, or rebuild the tag from a `data-src` placeholder and drop everything else. If your site ID was in a `data-site-id` attribute, it gets removed and the script logs `Please provide a valid site ID`.

**Platforms known to strip attributes:**

* Google Tag Manager
* WordPress optimization plugins with "delay JavaScript" enabled (WP Rocket, Perfmatters, FlyingPress, LiteSpeed Cache)
* Some WordPress page builders
* Certain website builders (Webflow, Wix, Squarespace in some configurations)
* Some CDN or caching plugins

**Solution:** Put the site ID in the script URL instead of a data attribute. Optimizers preserve the URL:

```html
<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
```

If your platform also rewrites the `src`, inject the script from JavaScript instead:

```javascript
<script>
  (function() {
    var el = document.createElement("script");
    el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
    el.defer = true;
    document.head.appendChild(el);
  })();
</script>
```

<Callout type="info">
  For detailed Google Tag Manager setup instructions, see our [Google Tag Manager Guide](/docs/guides/google-tag-manager).
</Callout>

### Ad Blockers [#ad-blockers]

In rare cases, ad blockers may block the Rybbit tracking script. While Rybbit is privacy-focused and doesn't use cookies for tracking, some aggressive ad blockers may still flag analytics scripts.

**How to check if an ad blocker is the issue:**

1. Temporarily disable your ad blocker
2. Refresh the page
3. Check the console again for the `rybbit` object

**Solutions:**

* **For your own testing**: Disable your ad blocker or add your site to the allowlist
* **For your visitors**: Consider setting up a [proxy](/docs/proxy-guide) to serve the script from your own domain, which significantly reduces the chance of being blocked

### Script Not in the Right Location [#script-not-in-the-right-location]

The Rybbit script should be placed in the `<head>` section of your HTML. If it's placed in the wrong location or loaded after the page has already finished loading, it may not work correctly.

**Verify the script placement:**

1. View your page source (right-click → **View Page Source**)
2. Search for `rybbit` or `script.js`
3. Confirm it appears within the `<head>...</head>` tags

### Incorrect Site ID [#incorrect-site-id]

Double-check that the `siteId` in your script URL (or your `data-site-id` attribute) matches the site ID shown in your Rybbit dashboard.

1. Go to your Rybbit dashboard
2. Navigate to your site's settings
3. Copy the site ID and compare it with what's in your script tag

### Content Security Policy (CSP) Blocking [#content-security-policy-csp-blocking]

If your site has a strict Content Security Policy, it may block the Rybbit script from loading or executing.

**Check for CSP errors:**

1. Open the browser console
2. Look for errors mentioning "Content Security Policy" or "CSP"

**Solution:** Add the Rybbit script domain to your CSP headers:

```
script-src 'self' https://app.rybbit.io;
connect-src 'self' https://app.rybbit.io;
```

If you're self-hosting Rybbit, replace `app.rybbit.io` with your Rybbit instance domain.

### Script Loading Too Late in SPAs [#script-loading-too-late-in-spas]

In single-page applications (React, Vue, Next.js, etc.), if the script loads after the initial page render, the automatic pageview might not fire.

**Solution:** Ensure the script is in your root HTML template (like `index.html` or `_document.js` in Next.js), not dynamically imported in a component.

For Next.js specifically, see our [Next.js Guide](/docs/guides/nextjs).

## Testing Your Installation [#testing-your-installation]

Once you've made changes, verify that tracking is working:

1. **Check the console**: Type `rybbit` to confirm the object exists
2. **Trigger a test event**: In the console, run:
   ```javascript
   rybbit.event("test_event")
   ```
3. **Check your dashboard**: Navigate to the Events tab in your Rybbit dashboard and look for "test\_event" (it may take a few seconds to appear)
4. **Check the Network tab**: In browser dev tools, go to the Network tab, filter by "track" or "rybbit", and verify requests are being sent with 200 status codes

## Still Having Issues? [#still-having-issues]

If you've tried all the above and are still not seeing traffic:

1. **Check the browser Network tab** for any failed requests to your Rybbit instance
2. **Verify your site ID** is correct in the dashboard
3. **Check if traffic is being filtered** - review your [IP exclusions](/docs/hiding-own-traffic) and [country exclusions](/docs/filter-traffic) to ensure your traffic isn't being blocked
4. **For self-hosted instances** - ensure your Rybbit server is running and accessible

***

**Related Documentation:**

* [Tracking Script Installation](/docs/script)
* [Track Events](/docs/track-events)
* [Proxy Guide](/docs/proxy-guide)
* [Google Tag Manager Guide](/docs/guides/google-tag-manager)
* [Hide Your Own Traffic](/docs/hiding-own-traffic)
* [Filter Traffic](/docs/filter-traffic)


# Tracking script (/docs/script)





To start tracking user activity on your website, add the Rybbit tracking script to your site's HTML.

## Installation [#installation]

The webpage should give you this script tag like this when you first add a website. Place it within the `<head>` section of your website. Include it on every page you wish to track.

```html
<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" async></script>
```

If you are self-hosting Rybbit `app.rybbit.io` will be domain of your Rybbit instance.

The site ID is passed in the script URL. The older `data-site-id="YOUR_SITE_ID"` attribute still works, but the URL form is recommended because script optimizers (WP Rocket, Perfmatters, FlyingPress and similar "delay JavaScript" features) rebuild script tags and drop `data-*` attributes, while leaving the URL intact.

<Callout type="info">
  **Bypass Ad Blockers**: Some ad blockers may block analytics scripts regardless of privacy compliance. To improve tracking accuracy, you can proxy the tracking script through your own domain. See our [Proxy Guide](/docs/proxy-guide) for setup instructions for Next.js, Nginx, Caddy, and more.
</Callout>

## Configuration [#configuration]

### Site Settings Configuration [#site-settings-configuration]

Most tracking options are configured through your site settings in the Rybbit dashboard. The script automatically fetches these settings when it loads:

* **Automatic Initial Pageview**: Track the first pageview when the script loads
* **SPA Navigation**: Automatically track navigation in single-page applications
* **URL Parameters**: Include or exclude query strings from tracked URLs
* **Outbound Links**: Track clicks to external websites
* **Error Tracking**: Capture JavaScript errors and unhandled promise rejections
* **Session Replay**: Record user interactions for debugging and UX analysis
* **Web Vitals**: Collect Core Web Vitals performance metrics

### Script Attributes [#script-attributes]

These are the attributes you can pass to the script tag.

| Attribute            | Type     | Default | Description                                                                                                                                                                                                                                                                        |
| :------------------- | :------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-skip-patterns` | `string` | `[]`    | A JSON string array of URL path patterns to ignore. Pageviews matching these patterns won't be tracked. Supports two types of wildcards: `*` (matches within a segment) and `**` (matches across segments), plus regex patterns prefixed with `re:`.                               |
| `data-mask-patterns` | `string` | `[]`    | A JSON string array of URL path patterns to mask for privacy. Pageviews matching these patterns will be tracked, but the actual URL path will be replaced with the pattern itself in analytics data. Supports the same wildcards and `re:` regex patterns as `data-skip-patterns`. |
| `data-debounce`      | `string` | `"500"` | The delay (in milliseconds) before tracking a pageview after URL changes via the History API (`pushState`, `replaceState`). Set to `0` to disable debouncing.                                                                                                                      |
| `data-tag`           | `string` | `""`    | A label applied to all events from this script instance. Useful for A/B testing, deploy versioning, or cohort segmentation. Max 256 characters. See [Tagging](/docs/tagging).                                                                                                      |

{/* ### Feature Flags

  The tracking script automatically evaluates client and both-runtime feature flags when it loads. Read evaluated flags from `window.rybbit` after the script is ready:

  ```javascript
  window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);
  const config = rybbit.flagPayload("checkout_config", {});
  });
  ```

  Available methods:

  | Method | Description |
  | --- | --- |
  | `flag(key, fallback)` | Returns a boolean, variant key, or fallback value. Also records a feature flag exposure once per flag value/version. |
  | `flagPayload(key, fallback)` | Returns the payload for a flag, variant, or remote config. |
  | `flags()` | Returns all evaluated flag values. |
  | `flagPayloads()` | Returns all available flag payloads. |

  See [Feature Flags](/docs/feature-flags) for targeting rules, remote config, and server-side evaluation. */}

### Session Replay Attributes [#session-replay-attributes]

These attributes configure rrweb session replay behavior. They only apply when session replay is enabled in your site settings.

| Attribute                         | Type          | Default                          | Description                                                                                                                   |
| :-------------------------------- | :------------ | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `data-replay-mask-text-selectors` | `string`      | `[]`                             | A JSON string array of CSS selectors for elements whose text content should be masked. Example: `'[".user-name", "#email"]'`. |
| `data-replay-block-class`         | `string`      | `"rr-block"`                     | CSS class name for elements to exclude entirely from recording. Elements with this class won't appear in replays.             |
| `data-replay-block-selector`      | `string`      | `null`                           | CSS selector for elements to exclude from recording. Example: `".sensitive-content, #private-section"`.                       |
| `data-replay-ignore-class`        | `string`      | `"rr-ignore"`                    | CSS class name for elements whose input events should be ignored. The element appears but interactions aren't recorded.       |
| `data-replay-ignore-selector`     | `string`      | `null`                           | CSS selector for elements whose input events should be ignored. Example: `"input[name='credit-card']"`.                       |
| `data-replay-mask-text-class`     | `string`      | `"rr-mask"`                      | CSS class name for elements whose text content should be masked (shown as asterisks).                                         |
| `data-replay-mask-all-inputs`     | `boolean`     | `true`                           | When true, all input values are masked as asterisks for privacy. Set to `"false"` to disable.                                 |
| `data-replay-mask-input-options`  | `JSON object` | `{"password":true,"email":true}` | Specify which input types to mask. Example: `'{"password":true,"email":true,"tel":true}'`.                                    |
| `data-replay-collect-fonts`       | `boolean`     | `true`                           | When true, website fonts are collected for accurate replay rendering. Set to `"false"` to reduce data size.                   |
| `data-replay-sampling`            | `JSON object` | See below                        | Configure event sampling to reduce data volume. See sampling options below.                                                   |
| `data-replay-slim-dom-options`    | `JSON object` | See below                        | Configure which DOM elements to exclude from recording. See slimDOM options below.                                            |

### Pattern Matching Details [#pattern-matching-details]

For `data-skip-patterns` and `data-mask-patterns`, two types of wildcards are supported:

* `*` - Matches any characters within a single path segment (doesn't match across `/`)
* `**` - Matches any characters across multiple path segments (includes `/`)

Examples:

* `/admin/*` matches `/admin/dashboard` but not `/admin/users/list`
* `/admin/**` matches both `/admin/dashboard` and `/admin/users/list`
* `/blog/*/comments` matches `/blog/post-123/comments` but not `/blog/category/post/comments`

Regex patterns are also supported when prefixed with `re:`. The regex is used as-is, so add `^` and `$` if you want a full-path match.

Examples:

* `re:^/users/\\d+$` matches `/users/123` but not `/users/abc`
* `re:^/private/.*$` matches anything under `/private/`

Example usage:

```html
data-skip-patterns='["/admin/**", "/blog/drafts/*", "/preview/**"]'
data-mask-patterns='["/users/*/settings", "/accounts/**", "/orders/*/details"]'
```

Regex usage:

```html
data-skip-patterns='["re:^/private/.*$"]'
data-mask-patterns='["re:^/users/\\d+/settings$"]'
```

**Example with debugging overrides:**

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="456"
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-debounce="300"
></script>
```

## Session Replay Configuration [#session-replay-configuration]

When session replay is enabled in your site settings, you can fine-tune the recording behavior using the attributes above. This section covers the more complex configuration options.

### Privacy Controls [#privacy-controls]

Protect sensitive user information using these options:

| Option                 | Best For                                                           |
| ---------------------- | ------------------------------------------------------------------ |
| `data-replay-block-*`  | Completely hide elements (e.g., admin panels, modals with PII)     |
| `data-replay-ignore-*` | Show elements but don't record interactions (e.g., form fields)    |
| `data-replay-mask-*`   | Show element structure but hide text content (e.g., names, emails) |

**Example - Comprehensive privacy setup:**

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="123"
  data-replay-block-selector=".admin-panel, #payment-modal"
  data-replay-ignore-selector="input[name='ssn'], input[name='credit-card']"
  data-replay-mask-text-selectors='[".user-name", "#email", "[data-pii]"]'
  data-replay-mask-input-options='{"password":true,"email":true,"tel":true}'
></script>
```

### Sampling Configuration [#sampling-configuration]

The `data-replay-sampling` attribute controls how frequently events are recorded. Lower sampling rates reduce data volume but may miss some interactions.

**Default sampling configuration:**

```json
{
  "mousemove": false,
  "mouseInteraction": {
    "MouseUp": false,
    "MouseDown": false,
    "Click": true,
    "ContextMenu": false,
    "DblClick": true,
    "Focus": true,
    "Blur": true,
    "TouchStart": false,
    "TouchEnd": false
  },
  "scroll": 500,
  "input": "last",
  "media": 800
}
```

**Sampling options:**

* `mousemove`: `false` to disable, or number (ms) for sampling interval
* `scroll`: Sampling interval in milliseconds (e.g., `500` = sample every 500ms)
* `input`: `"last"` to only record final value, or `"all"` to record every keystroke
* `media`: Sampling interval for media events in milliseconds

**Example - Enable mouse tracking for UX analysis:**

```html
data-replay-sampling='{"mousemove":100,"scroll":150}'
```

### SlimDOM Options [#slimdom-options]

The `data-replay-slim-dom-options` attribute controls which DOM elements are excluded from recording to reduce data size.

**Default slimDOM configuration:**

```json
{
  "script": false,
  "comment": true,
  "headFavicon": true,
  "headWhitespace": true,
  "headMetaDescKeywords": true,
  "headMetaSocial": true,
  "headMetaRobots": true,
  "headMetaHttpEquiv": true,
  "headMetaAuthorship": true,
  "headMetaVerification": true
}
```

Set to `true` to enable all slimDOM options, or `false` to disable all:

```html
data-replay-slim-dom-options="true"
```

### Complete Example [#complete-example]

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="456"
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-debounce="300"
  data-replay-block-selector=".sensitive-content"
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-replay-mask-all-inputs="true"
  data-replay-collect-fonts="false"
  data-replay-sampling='{"mousemove":false,"scroll":500}'
></script>
```


# Segments (/docs/segments)





A segment is a named, reusable set of [filters](/docs/feature-guides/main-tab#filters). Instead of rebuilding "mobile visitors from Germany who came from search" every time, save it once and apply it to the main dashboard, pages, sessions, funnels, journeys, retention, and exports with one click.

Segments live inside the **Filter** button. Nothing else changes in the dashboard: applying a segment expands its filters into the same filter bar every report already reads.

## Creating a segment [#creating-a-segment]

Open the **Filter** button and switch to the **Segments** tab. There are two ways to create one:

<Steps>
  <Step>
    ### From scratch [#from-scratch]

    Click **New segment**. The dialog has its own filter editor, so you can build the definition without applying anything to the dashboard first.
  </Step>

  <Step>
    ### From the current filters [#from-the-current-filters]

    Once the dashboard has filters applied, the Segments tab offers **Save current filters as segment**. The dialog opens with those filters and a suggested name.
  </Step>
</Steps>

Every segment has:

* **Name** — what the group means to you, such as "Paid traffic" or "Logged-in users"
* **Filters** — at least one. Every filter must match; multiple values inside one filter are alternatives
* **Available on** — this site only, or every site in the organization (organization-wide segments can only be created by admins and owners)
* **Description** — optional notes for your team
* **Show on the public dashboard and private links** — off by default

<Callout type="info">
  Filters in a segment are validated against the same schema as the filter bar, so a segment can never save something the dashboard could not query.
</Callout>

## Applying a segment [#applying-a-segment]

In the **Segments*&#x2A; tab, click a segment to apply it. It appears in the filter bar as a single chip named after the segment. Click the chip to see the filters it contains; click the &#x2A;*×** to remove all of them at once.

Ad-hoc filters work alongside an applied segment. Add a filter the usual way and it is ANDed with the segment. If one of the segment's own filters is changed on the dashboard, the chip reads &#x2A;*(edited)** so you know the row no longer matches the saved definition; the segment itself is unchanged.

Segments are part of the URL, so a dashboard link with a segment applied opens the same view for whoever you share it with.

## Editing and deleting [#editing-and-deleting]

Use the &#x2A;*⋯** menu on a segment in the Segments tab, or **Edit segment** from the applied chip. Changes apply everywhere the segment is used. Deleting a segment removes it for everyone; links that already expanded its filters keep working.

## Permissions [#permissions]

| Role                                    | Read and apply                                   | Create                     | Edit and delete       |
| --------------------------------------- | ------------------------------------------------ | -------------------------- | --------------------- |
| Owner or admin                          | All segments                                     | Site and organization-wide | Any segment           |
| Member                                  | All segments                                     | Site segments              | Segments they created |
| Public dashboard or private-link viewer | Segments marked as shown on the public dashboard | —                          | —                     |

## API and MCP [#api-and-mcp]

Every analytics endpoint accepts a `segment_id` query parameter that is expanded server-side, ANDed with any `filters` you also pass. Segments themselves are managed through the [Segments endpoints](/docs/api/segments/list). The [MCP server](/docs/mcp) exposes `list_segments` and `apply_segment`.


# Self-hosted vs Cloud (/docs/self-host-vs-cloud)





Rybbit offers two deployment options: a fully-managed [cloud version](https://rybbit.com) and a [self-hosted](/docs/self-hosting) solution. This guide will help you choose the right option for your needs.

## Quick Comparison [#quick-comparison]

| Feature                               | Cloud                                                                                                                             | Self-Hosted                                                                                                                                          |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup Time**                        | Minutes                                                                                                                           | 30 - 120 minutes                                                                                                                                     |
| **Maintenance Required**              | None                                                                                                                              | Regular updates                                                                                                                                      |
| **Cookieless & Privacy friendly**     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Web Analytics**                     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **API**                               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Globe**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Session Replays**                   | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth="3" /> (On pro tier)</span> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Funnels**                           | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Goals**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Sessions**                          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Journeys**                          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Users**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Retention**                         | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Error tracking**                    | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Organizations/Teams**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Pages View**                        | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />                                                                                    |
| **Web Vitals**                        | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Email reports**                     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />                                                                                    |
| **Google Search Console integration** | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth="3" /> (Requires Google OAuth env vars)</span> |


# Quick start (/docs/self-hosting)





This guide will walk you through setting up your own instance of Rybbit using our setup script. If you want to manually setup Rybbit using the Docker Compose file, check out our [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) guide.

## Prerequisites [#prerequisites]

Before you begin, ensure you have the following:

* **A VPS:** Try to get one with at least 2GB of RAM.
* **A Domain Name:** You'll need a domain or subdomain (e.g., `tracking.yourdomain.com`) pointed to your VPS's IP address. HTTPS is required because browsers block tracking scripts served over insecure HTTP.

<Callout type="info">
  This guide has been tested on Ubuntu 24 LTS (x86\_64). If your server is ARM, it must be at least ARMv8.2-A for Clickhouse support.
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Point Your Domain to Your VPS [#point-your-domain-to-your-vps]

    Configure your domain's DNS settings to point to your VPS's public IP address. This usually involves:

    1. Finding your VPS's public IPv4 address (from your hosting provider, e.g., Hetzner).
    2. Logging into your domain registrar or DNS provider (e.g., GoDaddy, Namecheap, Cloudflare).
    3. Adding an `A` record:
       * **Host/Name:** Your desired subdomain (e.g., `tracking`) or `@` for the root domain.
       * **Value:** Your VPS's IPv4 address.
       * **Proxy Status:** When using Cloudflare, either:
         * Set to "DNS only" (recommended for most setups)
         * Or if keeping the proxy enabled, set SSL/TLS encryption mode to "Full" or "Full (strict)" in your Cloudflare dashboard under SSL/TLS settings

    <Callout type="warning">
      If you keep Cloudflare's proxy enabled and your domain has other services not running on HTTPS, using Full or Full (strict) mode might cause issues with those services. In such cases, either use "DNS only" mode or ensure all your services support HTTPS.
    </Callout>

    DNS changes might take some time to propagate globally. Use [DNS Checker](https://dnschecker.org/) to verify.
  </Step>

  <Step>
    ### Install Docker Engine [#install-docker-engine]

    Connect to your VPS via SSH.

    Follow the official Docker Engine installation instructions for your Linux distribution:
    [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
  </Step>

  <Step>
    ### Clone the Rybbit Repository [#clone-the-rybbit-repository]

    Clone the project repository from GitHub (Git is usually pre-installed on most server distributions):

    ```bash
    git clone https://github.com/rybbit-io/rybbit.git
    cd rybbit
    ```
  </Step>

  <Step>
    ### Run the Setup Script [#run-the-setup-script]

    The repository includes a setup script that configures the necessary environment variables (including generating a secure secret) and starts the application using Docker Compose.

    <Callout type="warning">
      Important: Make all scripts executable before proceeding!

      ```bash
      chmod +x *.sh
      ```
    </Callout>

    Run the setup script, replacing `your.domain.name` with the domain or subdomain you configured in the prerequisites:

    ```bash
    ./setup.sh your.domain.name
    ```

    If you want to enable 3D map visualizations, you can add the `--mapbox-token` flag:

    ```bash
    ./setup.sh your.domain.name --mapbox-token YOUR_MAPBOX_TOKEN
    ```

    The script will create a `.env` file and then build and start the containers. This might take a few minutes the first time.

    <Callout type="info">
      By default, we assume you are on a blank VPS and automatically setup a Caddy webserver. If you want to use your own webserver or need more control over the setup, check out:

      * [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) - For users with existing reverse proxies or deployment tools
      * [Advanced Self-Hosting Guide](/docs/self-hosting-guides/self-hosting-advanced) - For custom configurations and Nginx setup
    </Callout>
  </Step>

  <Step>
    ### Sign Up [#sign-up]

    Once the services are running and DNS has propagated, Caddy (the webserver) will automatically obtain an SSL certificate for your domain.

    Open your browser and navigate to `https://your.domain.name/signup` (using the domain you provided to the setup script).

    Create your admin account. You can then log in and start adding your websites!
  </Step>
</Steps>

If you run into any issues or need help, feel free to join our Discord community!


# Site settings (/docs/site-settings)







Access your site settings by clicking the settings icon in your site's Rybbit dashboard.

<img alt="site settings" src="__img0" />

## Privacy & Security [#privacy--security]

### Public Analytics [#public-analytics]

Make your analytics publicly accessible by enabling the "Public Analytics" toggle.

* External viewers have read-only access to your analytics data
* Viewers cannot edit settings, reports, funnels, or goals
* Your other websites are not affected

### User ID Salting [#user-id-salting]

Rybbit stores user IDs as a hashed combination of IP + user agent. This allows identifying users across sessions, but may be considered storing personally identifiable data under GDPR.

Enable "User ID Salting" to have Rybbit forget about unique users every day. If a user visits 10 times in one day, they count as one user with 10 sessions. But if they visit once a day for 10 days, they appear as a new user each day.

**Downsides of enabling user ID salting:**

* User session history beyond 24 hours is not available
* Unique user counts over periods longer than 24 hours will be inflated
* The user retention page becomes effectively useless

### Block Bot Traffic [#block-bot-traffic]

Enable "Block Bot Traffic" to prevent detected bot traffic from being tracked in your normal analytics. See [Bot detection](/docs/bot-detection) for how Rybbit identifies and stores bot traffic.

### Track IP Address [#track-ip-address]

Enable "Track IP Address" to store the IP address of visitors.

<Callout type="warn">
  This is not GDPR compliant. Only enable if you have a legitimate need and proper consent mechanisms in place.
</Callout>

## Analytics Features [#analytics-features]

### Session Replay <span className="text-green-500 text-sm">(Pro)</span> [#session-replay-pro]

Record and replay user sessions to understand user behavior. This feature allows you to see exactly how users interact with your site.

### Web Vitals <span className="text-green-500 text-sm">(Standard)</span> [#web-vitals-standard]

Track Core Web Vitals metrics including:

* **LCP** (Largest Contentful Paint)
* **CLS** (Cumulative Layout Shift)
* **INP** (Interaction to Next Paint)
* **FCP** (First Contentful Paint)
* **TTFB** (Time to First Byte)

### Error Tracking <span className="text-green-500 text-sm">(Standard)</span> [#error-tracking-standard]

Capture JavaScript errors and exceptions from your site to identify and fix issues affecting your users.

### Track Outbound Links [#track-outbound-links]

Track when users click on external links leaving your site. Enabled by default.

### Track URL Parameters [#track-url-parameters]

Include query string parameters in page tracking. Enabled by default. Disable if you want cleaner URLs in your analytics or need to exclude sensitive parameters.

### Track Initial Page View [#track-initial-page-view]

Automatically track the first page view when the tracking script loads. Enabled by default.

### Track SPA Navigation [#track-spa-navigation]

Automatically track navigation in single-page applications (SPAs). Enabled by default. This detects URL changes via the History API and tracks them as page views.

## Traffic Filtering [#traffic-filtering]

### IP Exclusions [#ip-exclusions]

Block specific IP addresses or ranges from being tracked. Supports:

* Individual IP addresses (e.g., `192.168.1.1`)
* CIDR notation (e.g., `192.168.1.0/24`)
* IPv4 ranges (e.g., `192.168.1.1-192.168.1.255`)

### Country Exclusions [#country-exclusions]

Block all traffic from specific countries using ISO country codes (e.g., `US`, `DE`, `FR`).

### Path Exclusions [#path-exclusions]

Exclude traffic to specific pages. Use `*` as a wildcard (e.g., `/admin/*` or `/preview`). Matching is case-insensitive. Up to 100 path exclusions are allowed.

### Hostname Exclusions [#hostname-exclusions]

Exclude traffic from specific hostnames such as staging or preview domains. Use `*` as a wildcard (e.g., `localhost` or `*.vercel.app`). Matching is case-insensitive. Up to 100 hostname exclusions are allowed.

### User Agent Exclusions [#user-agent-exclusions]

Exclude traffic from user agents containing any of these terms. Matching is a case-insensitive substring (e.g., `HeadlessChrome`). Up to 100 user agent exclusions are allowed.

All of these exclusions work at the server level, ensuring blocked traffic never reaches your analytics database.

## Embeds [#embeds]

Show Rybbit data on another site with an embeddable iframe.

* **Widget Embeds** show a compact live visitor widget. Enable them from the **Widget Embeds** tab. This is independent of Public Analytics and only exposes the data the widget displays. See the [Widget Embeds guide](/docs/embeds/widget) for details.
* **Dashboard Embed** shows the analytics dashboard in an iframe. Configure it from the **Dashboard Embed** tab. It uses a generated private link, not Public Analytics. See the [Dashboard Embed guide](/docs/embeds/dashboard) for details.

## Google Search Console <span className="text-green-500 text-sm">(Cloud)</span> [#google-search-console-cloud]

Connect your Google Search Console account to see search performance data alongside your analytics.

## Change Domain [#change-domain]

Update the domain for your site. Changing domains does not affect existing data - all historical analytics are preserved.

## Delete Site [#delete-site]

Permanently delete a site and all associated data.

<Callout type="warn">
  This action cannot be undone. All analytics data, reports, funnels, and goals will be permanently deleted.
</Callout>


# Tagging (/docs/tagging)



Tags let you label all events from a script instance with a string identifier. This is useful for A/B testing, deploy labeling, cohort segmentation, and any scenario where you want to slice your analytics by a custom dimension that applies to the entire page.

If you need Rybbit to choose a value at runtime, gradually roll out a feature, or serve remote config, use [Feature Flags](/docs/feature-flags) instead.

## How It Works [#how-it-works]

Add a `data-tag` attribute to your Rybbit script tag. Every event (pageviews, custom events, outbound clicks, etc.) sent from that page will include the tag value, which is stored in ClickHouse and available as a filter in the dashboard.

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="YOUR_SITE_ID"
  data-tag="variant-a"
></script>
```

The tag is a simple string with a maximum length of 256 characters. If `data-tag` is not set or is empty, no tag is stored.

## Use Cases [#use-cases]

### A/B Testing [#ab-testing]

Serve different script tags to different user groups and compare behavior:

```html
<!-- Variant A -->
<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-a"></script>

<!-- Variant B -->
<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-b"></script>
```

Then filter by tag in the dashboard to compare metrics between variants.

### Deploy / Release Labeling [#deploy--release-labeling]

Tag events with the current deploy version to correlate releases with changes in user behavior or errors:

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="1"
  data-tag="v2.4.1"
></script>
```

### Cohort Segmentation [#cohort-segmentation]

Label traffic from different sources, campaigns, or user segments:

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="1"
  data-tag="beta-users"
></script>
```

## Filtering by Tag [#filtering-by-tag]

Once events with tags are flowing in, you can filter by tag anywhere in the dashboard:

1. Click the **filter** button in the dashboard header
2. Select **Tag** from the filter parameter dropdown
3. Choose an operator (is, is not, contains, etc.)
4. Enter the tag value

The tag filter works on all dashboard pages including overview, pages, referrers, events, users, funnels, and goals.

## API Usage [#api-usage]

When sending events via the [HTTP API](/docs/api/sending-events), include `tag` in the request body:

```json
{
  "site_id": "YOUR_SITE_ID",
  "type": "pageview",
  "hostname": "example.com",
  "pathname": "/",
  "tag": "variant-a"
}
```

## Important Notes [#important-notes]

* Each script instance can only have one tag. If you need multiple dimensions, consider using [custom event properties](/docs/track-events) instead.
* Tags are set at the script level, not per-event. All events from a page load share the same tag.
* The tag value is stored as-is (no hashing or transformation).
* Empty or missing `data-tag` attributes result in no tag being stored.

**Related Documentation:**

* [Tracking Script](/docs/script)
* [Track Events](/docs/track-events)
* [Identify Users](/docs/identify-users)


# Teams (/docs/teams)







Teams let you group sites together and control which organization members can access them. This is useful for organizations managing multiple properties where different people are responsible for different sites.

Access teams by clicking on "Teams" or going to [app.rybbit.io/settings/teams](https://app.rybbit.io/settings/teams).

<img alt="teams" src="__img0" />

## How Teams Work [#how-teams-work]

A team has three things:

* **A name** — identifies the team (e.g. "Marketing Sites", "Client Projects")
* **Members** — organization members assigned to the team
* **Sites** — the sites that belong to the team

When a member is assigned to a team, they can access all sites within that team. Admins and owners always have access to all sites regardless of team assignments.

<Callout type="info">
  Teams are an organizational tool for admins and owners. Members with the "Member" role can only see sites that belong to their assigned teams (unless they have unrestricted access).
</Callout>

## Creating a Team [#creating-a-team]

1. Go to **Settings > Teams**
2. Click the **Create Team** button
3. Enter a team name
4. Select which members should belong to the team
5. Select which sites the team should have access to
6. Click **Create Team**

You can also create a team directly from the team filter on the home page.

## Managing Teams [#managing-teams]

### Editing a Team [#editing-a-team]

Click the edit icon on any team card to update its name, members, or site assignments.

### Deleting a Team [#deleting-a-team]

Click the delete icon on a team card. Sites assigned to the team will become unassigned and visible to all members.

<Callout type="warn">
  Deleting a team removes all member-to-site associations through that team. Members who only had access via the deleted team will lose access to those sites.
</Callout>

## Filtering by Team [#filtering-by-team]

On the home page, use the team selector in the toolbar to filter the site list by team. The options are:

* **All Teams** — show all sites
* **No Team** — show only sites not assigned to any team
* **Specific team** — show only sites belonging to that team

## Assigning Teams During Invitation [#assigning-teams-during-invitation]

When [inviting a new member](/docs/inviting-users), you can optionally assign them to a team. When the member accepts the invitation, they will automatically be added to the selected team.

## Permissions [#permissions]

| Role       | Can create teams | Can edit/delete teams | Can view team-restricted sites     |
| ---------- | ---------------- | --------------------- | ---------------------------------- |
| **Owner**  | Yes              | Yes                   | All sites                          |
| **Admin**  | Yes              | Yes                   | All sites                          |
| **Member** | No               | No                    | Only sites in their assigned teams |


# Track Events (/docs/track-events)



The script exposes a global object `window.rybbit` with functions for manual tracking of events, as well as the ability to track events using data attributes on HTML elements.

## Using Data Attributes [#using-data-attributes]

You can track custom events by adding data attributes to any HTML element:

```html
<!-- Basic event tracking -->
<button data-rybbit-event="signup_clicked">Sign Up</button>

<!-- Event with custom properties -->
<button
  data-rybbit-event="purchase_click"
  data-rybbit-prop-product="premium"
  data-rybbit-prop-price="49.99"
>
  Buy Now
</button>
```

This approach requires no JavaScript and works on any clickable element.

## Available Functions [#available-functions]

### `window.rybbit.event(eventName, properties)` [#windowrybbiteventeventname-properties]

Tracks a custom event with optional properties.

* `eventName` (String): The name of the custom event (max 256 characters).
* `properties` (Object, Optional): An object containing custom data (max 2KB characters). Only strings numbers are supported as values.

```javascript
// Track a simple custom event
window.rybbit.event("Signup Button Clicked");

// Track a custom event with properties
window.rybbit.event("Item Added To Cart", {
  itemId: "PROD123",
  price: 49.99,
  category: "Clothing"
});
```

### `window.rybbit.pageview()` [#windowrybbitpageview]

Tracks a pageview. Useful when automatic SPA navigation tracking is disabled in your site settings, or when you need to manually trigger a pageview.

```javascript
// Track a pageview
window.rybbit.pageview();
```

## TypeScript Support [#typescript-support]

Put this as `rybbit.d.ts` anywhere in your project to avoid having to do `(window as any).rybbit.event()` everywhere.

```typescript
interface Rybbit {
    /**
     * Tracks a page view
     */
    pageview: () => void;

    /**
     * Tracks a custom event
     * @param name Name of the event
     * @param properties Optional properties for the event
     */
    event: (name: string, properties?: Record<string, any>) => void;

    /**
     * Sets a custom user ID for tracking logged-in users
     * @param userId The user ID to set (will be stored in localStorage)
     * @param traits Optional user metadata (email, name, custom fields)
     */
    identify: (userId: string, traits?: Record<string, unknown>) => void;

    /**
     * Updates traits for the currently identified user
     * @param traits User metadata to merge with existing traits
     */
    setTraits: (traits: Record<string, unknown>) => void;

    /**
     * Clears the stored user ID
     */
    clearUserId: () => void;

    /**
     * Gets the currently set user ID
     * @returns The current user ID or null if not set
     */
    getUserId: () => string | null;

    /**
     * Manually tracks outbound link clicks
     * @param url The URL of the outbound link
     * @param text Optional text content of the link
     * @param target Optional target attribute of the link
     */
    trackOutbound: (url: string, text?: string, target?: string) => void;

    /**
     * Evaluates a feature flag and returns its value. Reading a flag records a
     * feature flag exposure once per flag value/version.
     * @param key The flag key
     * @param fallback Value returned before flags resolve or if the flag is inactive
     */
    flag: <T = unknown>(key: string, fallback?: T) => T;

    /**
     * Returns the payload for a feature flag or its selected variant.
     * Use this for remote config and multivariate payloads.
     * @param key The flag key
     * @param fallback Value returned before flags resolve or if the flag is inactive
     */
    flagPayload: <T = unknown>(key: string, fallback?: T) => T;

    /**
     * Returns all evaluated flag values keyed by flag key
     */
    flags: () => Record<string, unknown>;

    /**
     * Returns all available flag payloads keyed by flag key
     */
    flagPayloads: () => Record<string, unknown>;

    /**
     * Runs a callback once the tracking script and feature flags are ready.
     * Use this before reading flags during page initialization.
     * @param callback Receives the ready rybbit instance
     */
    onReady: (callback: (rybbit: Rybbit) => void) => void;
}

declare global {
    interface Window {
        rybbit: Rybbit;
    }
}

export {};
```

## Server-Side Tracking [#server-side-tracking]

For tracking events from server-side applications, mobile apps, or any platform outside the browser, you can use the HTTP API. This is useful for:

* Server-side event tracking (Node.js, Python, Go, etc.)
* Mobile app analytics (iOS, Android, Flutter)
* Backend integrations and webhooks
* Scenarios where the JavaScript snippet can't be used

See the [API documentation](/docs/api/sending-events) for detailed examples in multiple languages including authentication, parameters, and rate limiting information.

***

**Related Documentation:**

* [Identify Users](/docs/identify-users)
* [Behavior Analytics - Events Tab](/docs/behavior-analytics/events)
* [Behavior Analytics - Users Tab](/docs/behavior-analytics/users)
* [Behavior Analytics - Sessions Tab](/docs/behavior-analytics/sessions)
* [Product Analytics - Retention Guide](/docs/product-analytics/retention_guide)
* [Product Analytics - Funnels](/docs/product-analytics/funnels_guide)
* [API - Sending Events](/docs/api/sending-events)
* [Blog: Churn Rate vs Retention Rate](/blog/churn-rate-vs-retention-rate)
* [Web SDK Reference](/docs/sdks/web)


# Troubleshooting (/docs/troubleshooting)





## Full Docker Cleanup [#full-docker-cleanup]

If you encounter issues with Docker containers, images, or volumes and need to start fresh, you can perform a complete Docker cleanup. This will remove all containers, images, volumes, and custom networks.

<Callout type="warn">
  **Warning**: This will remove ALL Docker containers, images, and volumes on your system, not just Rybbit-related ones. Make sure you don't have other important Docker containers running.
</Callout>

### Steps for Complete Docker Cleanup [#steps-for-complete-docker-cleanup]

<Steps>
  <Step>
    ### Remove your environment file [#remove-your-environment-file]

    ```bash
    rm .env
    ```
  </Step>

  <Step>
    ### Stop all running containers: [#stop-all-running-containers]

    ```bash
    docker stop $(docker ps -q)
    ```
  </Step>

  <Step>
    ### Remove all containers (both running and stopped): [#remove-all-containers-both-running-and-stopped]

    ```bash
    docker rm -f $(docker ps -aq)
    ```
  </Step>

  <Step>
    ### Remove all images: [#remove-all-images]

    ```bash
    docker rmi -f $(docker images -q)
    ```
  </Step>

  <Step>
    ### Remove all volumes: [#remove-all-volumes]

    ```bash
    docker volume rm -f $(docker volume ls -q)
    ```
  </Step>

  <Step>
    ### Remove all custom networks (preserves default networks): [#remove-all-custom-networks-preserves-default-networks]

    ```bash
    docker network rm $(docker network ls | grep -v "bridge\|host\|none" | awk '{print $1}')
    ```
  </Step>
</Steps>

### Alternative: Rybbit-Specific Cleanup [#alternative-rybbit-specific-cleanup]

If you only want to clean up Rybbit-related Docker resources without affecting other containers, use these commands instead:

```bash
# Stop and remove Rybbit containers
docker-compose down

# Remove Rybbit images
docker-compose down --rmi all

# Remove Rybbit volumes (this will delete your data!)
docker-compose down --volumes

# Complete Rybbit cleanup
docker-compose down --rmi all --volumes --remove-orphans
```

### After Cleanup [#after-cleanup]

Once you've completed the cleanup, you can restart Rybbit by following the setup instructions:

```bash
# Copy environment file
cp .env.example .env

# Edit .env with your configuration
# Then start the services
docker-compose up -d
```

## ClickHouse keeps crashing on a Proxmox VM [#clickhouse-keeps-crashing-on-a-proxmox-vm]

ClickHouse requires the SSE 4.2 instruction set. Proxmox VMs default to a generic CPU type (like `kvm64` or `x86-64-v2-AES`) that doesn't expose all of the host CPU's instruction sets to the VM, which causes ClickHouse to fail with `Illegal instruction` errors or get stuck in a restart loop.

To fix this, set the VM's CPU type to `host` so it passes through the physical CPU directly:

<Steps>
  <Step>
    ### Open the VM's hardware settings [#open-the-vms-hardware-settings]

    In the Proxmox web UI, select your VM, then go to **Hardware** → **Processors** → **Edit**.
  </Step>

  <Step>
    ### Set the CPU type to `host` [#set-the-cpu-type-to-host]

    Change the **Type** dropdown to `host` and click **OK**.
  </Step>

  <Step>
    ### Fully stop and start the VM [#fully-stop-and-start-the-vm]

    A reboot from inside the guest is not enough — do a full **Stop** and then **Start** from Proxmox for the CPU change to take effect.
  </Step>
</Steps>

<Callout type="info">
  The `host` CPU type can prevent live migration between Proxmox nodes with different CPU models. If you need migration, any CPU type that includes SSE 4.2 (e.g. `x86-64-v2-AES` on a host that supports it, or newer) may also work — but `host` is the most reliable option.
</Callout>

## I ran out of disk space [#i-ran-out-of-disk-space]

Regular web analytics events take up almost no space in Clickhouse, so it is very unlikely that you ran out of disk space from from this. There are two main reasons why you might have run out of disk space:

### 1. You are using session replay [#1-you-are-using-session-replay]

On self-hosted instances where we don't have access to S3 compatible object storage, session replays are stored in Clickhouse. Each session replay is at least 1000x the data footprint of the web analytics events. So it's very easy to run out of disk space.

We have a 30 day retention policy for session replays events, so if you turn off session replay, your disk space will slowly come back. If you need to immediately free up space, you can truncate the session replays table:

```bash
docker exec -it clickhouse clickhouse-client --database analytics

TRUNCATE TABLE session_replay_events;
TRUNCATE TABLE session_replay_metadata;
```

### 2. You didn't mount the Clickhouse log suppression configs [#2-you-didnt-mount-the-clickhouse-log-suppression-configs]

In our [docker-compose.yml](https://github.com/rybbit-io/rybbit/blob/master/docker-compose.yml), we have a config for Clickhouse that suppresses logs. Clickhouse stores a ton of logs in the log tables by default. This will quickly fill up your disk space if left unchecked.

If you follow the standard installation process, the configs are already mounted for you. If you rolled your own Docker setup, you need to mount the configs manually.


# Migration to v1.0 (/docs/v1-migration)





This guide covers the breaking changes and migration steps when upgrading to Rybbit v1.0.

## API Path Changes [#api-path-changes]

In v1.0, we've simplified the reverse proxy configuration by having the backend expect requests with the `/api/` prefix. This eliminates the need for custom path rewriting in reverse proxy configurations.

### If You're Using the Built-in Caddy Server [#if-youre-using-the-built-in-caddy-server]

**No action required.** The built-in Caddy server configuration has been automatically updated and will work without any changes on your part.

### If You're Using a Custom Reverse Proxy [#if-youre-using-a-custom-reverse-proxy]

**You need to remove any custom API path rewriting** from your reverse proxy configuration.

<Callout type="warn">
  **Important:** If you were using a custom reverse proxy (Nginx, Apache, etc.) with path rewriting rules for the `/api/` endpoint, you must remove these rules when upgrading to v1.0.
</Callout>

#### What to Remove [#what-to-remove]

Remove any configuration that strips or rewrites the `/api/` prefix when forwarding requests to the backend. Common examples include:

**Nginx - Remove these patterns:**

```nginx
# ❌ Remove this type of configuration
location /api/ {
    rewrite ^/api(/.*)$ $1 break;  # Remove this line
    proxy_pass http://localhost:3001/;  # Change trailing slash
}
```

**Update to:**

```nginx
# ✅ Correct v1.0 configuration
location /api/ {
    proxy_pass http://localhost:3001;  # No trailing slash, no rewrite
    proxy_set_header Host $host;
    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;
}
```

**Apache - Remove these patterns:**

```apache
# ❌ Remove this type of configuration
ProxyPass /api/ http://localhost:3001/
ProxyPassReverse /api/ http://localhost:3001/
```

**Update to:**

```apache
# ✅ Correct v1.0 configuration
ProxyPass /api/ http://localhost:3001/api/
ProxyPassReverse /api/ http://localhost:3001/api/
```

**Docker Compose with custom location rules:**

```yaml
# ❌ Remove rewrite rules like this
location /api/ {
    rewrite ^/api(/.*)$ $1 break;
    proxy_pass http://rybbit_backend:3001;
}
```

**Update to:**

```yaml
# ✅ Correct v1.0 configuration
location /api/ {
    proxy_pass http://rybbit_backend:3001;
}
```

#### Why This Change? [#why-this-change]

This change simplifies the reverse proxy setup and eliminates a common source of configuration errors. The backend now handles the `/api/` prefix internally, making the setup more straightforward and consistent across different proxy solutions.

## Migration Steps [#migration-steps]

1. **Backup your current configuration** before making any changes
2. **Update your reverse proxy configuration** to remove API path rewriting (if applicable)
3. **Update to v1.0** using the update script:
   ```bash
   ./update.sh
   ```
4. **Verify your setup** by checking that your Rybbit instance is accessible and functioning correctly

## Need Help? [#need-help]

If you encounter issues during migration or need assistance with your specific reverse proxy setup, feel free to join our Discord community for support.


# Compare Channel Performance (/docs/api/channel-performance)





The channel that sends the most visitors is rarely the channel that sends the most *customers*. This guide ranks each acquisition channel by conversion rate so you can see which sources punch above their weight — and which ones are vanity traffic.

**Endpoints used:**

* [`GET /metric`](/docs/api/overview/metric) — sessions broken down by channel
* [`GET /goals`](/docs/api/goals/list) — conversion metrics, scoped with a channel filter

<Callout type="info">
  The key technique here is the [`filters` parameter](/docs/api/getting-started#filter-parameters). Almost every endpoint accepts it, so you can take any site-wide metric and recompute it for a single segment — here, one channel at a time.
</Callout>

## The workflow [#the-workflow]

<Steps>
  <Step>
    **List your channels** and their session counts with `metric?parameter=channel`.
  </Step>

  <Step>
    **For each channel, fetch your goal's conversion rate** by calling `/goals` with a `channel` filter applied.
  </Step>

  <Step>
    **Rank by conversion rate** to reveal which channels actually drive outcomes.
  </Step>
</Steps>

## Full script [#full-script]

This script ranks every channel by the conversion rate of a chosen goal (here, goal `1` — your signup goal). Swap in whichever goal matters to your business.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="channel-performance.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const PRIMARY_GOAL_ID = 1; // the goal you care about

    const range = { start_date: '2024-01-01', end_date: '2024-01-31', time_zone: 'America/New_York' };

    async function get(path, params) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    // 1. All channels with their session counts
    async function getChannels() {
      const { data } = await get('/metric', { parameter: 'channel', limit: 20, ...range });
      return data.data; // [{ value: 'Organic Search', count: 5400, ... }]
    }

    // 2. Conversion rate for one channel, scoped with a filter
    async function goalForChannel(channel) {
      const filters = JSON.stringify([{ parameter: 'channel', type: 'equals', value: [channel] }]);
      const { data } = await get('/goals', { filters, ...range });
      return data.find((g) => g.goalId === PRIMARY_GOAL_ID);
    }

    async function rankChannels() {
      const channels = await getChannels();

      const rows = await Promise.all(
        channels.map(async (c) => {
          const goal = await goalForChannel(c.value);
          return {
            channel: c.value || 'Direct',
            sessions: c.count,
            conversions: goal?.total_conversions ?? 0,
            // conversion_rate comes back as a 0–1 fraction
            conversionRate: (goal?.conversion_rate ?? 0) * 100,
          };
        })
      );

      return rows.sort((a, b) => b.conversionRate - a.conversionRate);
    }

    rankChannels().then((rows) => {
      console.log('Channel'.padEnd(18), 'Sessions'.padStart(10), 'Conv.'.padStart(8), 'Rate'.padStart(8));
      for (const r of rows) {
        console.log(
          r.channel.padEnd(18),
          r.sessions.toLocaleString().padStart(10),
          String(r.conversions).padStart(8),
          `${r.conversionRate.toFixed(2)}%`.padStart(8)
        );
      }
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python title="channel_performance.py"
    import os, json, requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    PRIMARY_GOAL_ID = 1  # the goal you care about

    RANGE = {"start_date": "2024-01-01", "end_date": "2024-01-31", "time_zone": "America/New_York"}

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def get(path, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def get_channels():
        # 1. All channels with their session counts
        return get("/metric", parameter="channel", limit=20, **RANGE)["data"]["data"]


    def goal_for_channel(channel):
        # 2. Conversion rate for one channel, scoped with a filter
        filters = json.dumps([{"parameter": "channel", "type": "equals", "value": [channel]}])
        goals = get("/goals", filters=filters, **RANGE)["data"]
        return next((g for g in goals if g["goalId"] == PRIMARY_GOAL_ID), None)


    def rank_channels():
        rows = []
        for c in get_channels():
            goal = goal_for_channel(c["value"])
            rows.append({
                "channel": c["value"] or "Direct",
                "sessions": c["count"],
                "conversions": goal["total_conversions"] if goal else 0,
                # conversion_rate comes back as a 0–1 fraction
                "conversion_rate": (goal["conversion_rate"] if goal else 0) * 100,
            })
        return sorted(rows, key=lambda r: r["conversion_rate"], reverse=True)


    print(f"{'Channel':<18}{'Sessions':>10}{'Conv.':>8}{'Rate':>8}")
    for r in rank_channels():
        print(f"{r['channel']:<18}{r['sessions']:>10,}{r['conversions']:>8}{r['conversion_rate']:>7.2f}%")
    ```
  </Tab>
</Tabs>

## Reading the result [#reading-the-result]

```text
Channel             Sessions   Conv.    Rate
Referral               1,820     310    17.03%
Organic Search         5,400     642    11.89%
Direct                 4,220     451    10.69%
Email                    980      88     8.98%
Paid Search            2,310     142     6.15%
Social                 6,150     119     1.93%
```

Social sends the **most** traffic (6,150 sessions) but converts the **worst** (1.93%). Referral sends a fraction of the volume but converts nine times better. The takeaway writes itself: the referral partnerships deserve more investment, and the social strategy needs a hard look before more budget goes into it.

<Callout type="warn">
  Conversion rate alone can mislead on tiny samples — Email looks healthy at 9% but it's only 88 conversions. Always show the raw `sessions` and `conversions` columns next to the rate so a channel with 12 sessions and one fluke conversion doesn't top your list.
</Callout>

## Variations [#variations]

* **By UTM campaign instead of channel:** swap `parameter: 'channel'` for `parameter: 'utm_campaign'`, and filter on `utm_campaign` in the goals call. Same code, campaign-level granularity.
* **Engagement instead of conversion:** call [`/overview`](/docs/api/overview/overview) with the channel filter to compare `bounce_rate` and `session_duration` per channel — useful when you don't have a goal defined yet.
* **Full-funnel by channel:** run [`/funnels/analyze`](/docs/api/funnels/analyze) with a channel filter to see *where* in the funnel each channel's visitors fall out, not just the final rate.

## Next steps [#next-steps]

* [Find Where Users Drop Off](/docs/api/funnel-dropoff) — once you know your best channels, fix the funnel they pour into.
* [Automated Weekly Report](/docs/api/weekly-report) — add a channel league table to a scheduled digest.


# Find Where Users Drop Off (/docs/api/funnel-dropoff)





A funnel tells you *how many* people fall out at each step. The journeys endpoint tells you *where they went instead*. Putting them together turns "our signup funnel leaks at the pricing page" into "people leave the pricing page for the FAQ — they have unanswered questions."

**Endpoints used:**

* [`POST /funnels/analyze`](/docs/api/funnels/analyze) — step-by-step conversion and drop-off rates
* [`GET /journeys`](/docs/api/insights/journeys) — the most common navigation paths

## The workflow [#the-workflow]

<Steps>
  <Step>
    **Analyze the funnel** to get a drop-off rate for every step.
  </Step>

  <Step>
    **Find the worst step** — the one with the highest `dropoff_rate`.
  </Step>

  <Step>
    **Pull journeys that start at that step's page** using `stepFilters`, so you can see the most common next page for people who were there.
  </Step>
</Steps>

## Step 1 — Analyze the funnel [#step-1--analyze-the-funnel]

Define the path a converting user should take and post it to the analyze endpoint.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="Analyze the funnel"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;

    const range = { start_date: '2024-01-01', end_date: '2024-01-31', time_zone: 'America/New_York' };

    const funnelSteps = [
      { type: 'page',  value: '/',                 name: 'Homepage' },
      { type: 'page',  value: '/pricing',          name: 'Pricing' },
      { type: 'page',  value: '/signup',           name: 'Signup' },
      { type: 'event', value: 'signup_complete',   name: 'Complete' },
    ];

    async function analyzeFunnel() {
      const url = new URL(`${API}/api/sites/${SITE}/funnels/analyze`);
      Object.entries(range).forEach(([k, v]) => url.searchParams.set(k, v));

      const res = await fetch(url, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ steps: funnelSteps }),
      });
      const { data } = await res.json();
      return data; // array of { step_number, step_name, sessions, conversion_rate, dropoff_rate }
    }
    ```
  </Tab>

  <Tab value="Python">
    ```python title="Analyze the funnel"
    import os, requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]

    RANGE = {"start_date": "2024-01-01", "end_date": "2024-01-31", "time_zone": "America/New_York"}

    FUNNEL_STEPS = [
        {"type": "page",  "value": "/",               "name": "Homepage"},
        {"type": "page",  "value": "/pricing",        "name": "Pricing"},
        {"type": "page",  "value": "/signup",         "name": "Signup"},
        {"type": "event", "value": "signup_complete", "name": "Complete"},
    ]


    def analyze_funnel():
        res = requests.post(
            f"{API}/api/sites/{SITE}/funnels/analyze",
            params=RANGE,
            json={"steps": FUNNEL_STEPS},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        res.raise_for_status()
        return res.json()["data"]  # list of step results
    ```
  </Tab>
</Tabs>

A response looks like this — note that `dropoff_rate` is the percentage who left **between the previous step and this one**:

```json
{
  "data": [
    { "step_number": 1, "step_name": "Homepage", "sessions": 10000, "conversion_rate": 100,  "dropoff_rate": 0 },
    { "step_number": 2, "step_name": "Pricing",  "sessions": 4500,  "conversion_rate": 45,   "dropoff_rate": 55 },
    { "step_number": 3, "step_name": "Signup",   "sessions": 1800,  "conversion_rate": 18,   "dropoff_rate": 60 },
    { "step_number": 4, "step_name": "Complete", "sessions": 1080,  "conversion_rate": 10.8, "dropoff_rate": 40 }
  ]
}
```

## Step 2 — Find the worst step [#step-2--find-the-worst-step]

The leak isn't always the step with the fewest sessions — it's the step with the steepest **drop-off**. Pick the maximum `dropoff_rate`.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="Find the biggest leak"
    function biggestLeak(steps) {
      // Skip step 1 — it always has 0% drop-off
      return steps
        .filter((s) => s.step_number > 1)
        .reduce((worst, s) => (s.dropoff_rate > worst.dropoff_rate ? s : worst));
    }

    const steps = await analyzeFunnel();
    const leak = biggestLeak(steps);
    const enteredStep = steps[leak.step_number - 2]; // the step they were on before leaving

    console.log(
      `Worst leak: ${leak.dropoff_rate}% of users left after "${enteredStep.step_name}" ` +
      `instead of reaching "${leak.step_name}".`
    );
    ```
  </Tab>

  <Tab value="Python">
    ```python title="Find the biggest leak"
    def biggest_leak(steps):
        # Skip step 1 — it always has 0% drop-off
        return max((s for s in steps if s["step_number"] > 1), key=lambda s: s["dropoff_rate"])


    steps = analyze_funnel()
    leak = biggest_leak(steps)
    entered_step = steps[leak["step_number"] - 2]  # the step they were on before leaving

    print(
        f'Worst leak: {leak["dropoff_rate"]}% of users left after "{entered_step["step_name"]}" '
        f'instead of reaching "{leak["step_name"]}".'
    )
    ```
  </Tab>
</Tabs>

In the example above, the steepest drop-off is **60%, between Pricing and Signup** — of the 4,500 people who reached the pricing page, only 1,800 went on to signup. That makes the **pricing page** the one to investigate: it's where the audience was sitting right before the biggest leak.

## Step 3 — See where the leavers went [#step-3--see-where-the-leavers-went]

The [journeys endpoint](/docs/api/insights/journeys) ranks the most common page paths. Use `stepFilters` to anchor step `0` to the page people were dropping from — now every returned journey shows you a common *next* page for that audience.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="What did they do after the leaky page?"
    async function journeysFrom(page) {
      const stepFilters = JSON.stringify({ '0': page });
      const url = new URL(`${API}/api/sites/${SITE}/journeys`);
      url.searchParams.set('steps', '2');
      url.searchParams.set('limit', '10');
      url.searchParams.set('stepFilters', stepFilters);
      Object.entries(range).forEach(([k, v]) => url.searchParams.set(k, v));

      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      const { journeys } = await res.json();
      return journeys;
    }

    // The leaky step's page — '/pricing' in our example
    const leakyPage = funnelSteps[leak.step_number - 2].value;
    const journeys = await journeysFrom(leakyPage);

    console.log(`Where users go after ${leakyPage}:`);
    journeys
      .filter((j) => j.path[1] && j.path[1] !== '/signup') // exclude the intended next step
      .slice(0, 5)
      .forEach((j) => console.log(`  → ${j.path[1]}  (${j.count} sessions, ${j.percentage}%)`));
    ```
  </Tab>

  <Tab value="Python">
    ```python title="What did they do after the leaky page?"
    import json


    def journeys_from(page):
        res = requests.get(
            f"{API}/api/sites/{SITE}/journeys",
            params={"steps": 2, "limit": 10, "stepFilters": json.dumps({"0": page}), **RANGE},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        res.raise_for_status()
        return res.json()["journeys"]


    # The leaky step's page — '/pricing' in our example
    leaky_page = FUNNEL_STEPS[leak["step_number"] - 2]["value"]
    journeys = journeys_from(leaky_page)

    print(f"Where users go after {leaky_page}:")
    for j in [j for j in journeys if len(j["path"]) > 1 and j["path"][1] != "/signup"][:5]:
        print(f'  → {j["path"][1]}  ({j["count"]} sessions, {j["percentage"]}%)')
    ```
  </Tab>
</Tabs>

### The insight [#the-insight]

```text
Where users go after /pricing:
  → /faq          (1,240 sessions, 27.6%)
  → /             (820 sessions, 18.2%)
  → /enterprise   (610 sessions, 13.6%)
```

More than a quarter of people who hit Pricing and didn't sign up went to the FAQ — a strong signal that pricing raises questions your FAQ has to answer. That's a far more actionable finding than "the pricing page has a 60% drop-off."

<Callout type="info">
  **Quantify before you act.*&#x2A; Combine the funnel and journey numbers into a one-line business case: &#x2A;"2,700 users/month leave Pricing; 28% head to the FAQ. Surfacing the top FAQ answers on the pricing page could recover a meaningful share of them."*
</Callout>

## Next steps [#next-steps]

* [Compare Marketing Channel Performance](/docs/api/channel-performance) — find out which traffic sources fill the top of this funnel with people who actually convert.
* [Funnels API reference](/docs/api/funnels/analyze) — event steps, property matching, and per-step session lookups.


# Getting Started (/docs/api/getting-started)





<Callout type="warn">
  The API is currently in beta. There may be breaking changes as we continue to improve and expand the API.
</Callout>

## API Playground [#api-playground]

The easiest way to explore and test the API is using the built-in **API Playground** in your Rybbit dashboard. Access it by navigating to any site and clicking "API Playground" in the sidebar.

The playground provides:

* **Endpoint browser** - Browse all available API endpoints
* **Parameter controls** - Configure request parameters with a visual interface
* **Exact time ranges** - Test date ranges with optional start and end times
* **Live responses** - See real API responses with your actual data
* **Code generation** - Copy ready-to-use code snippets

This is the recommended way to familiarize yourself with the API before integrating it into your applications.

## Guides [#guides]

Looking for what to *build* with the API? These end-to-end recipes chain endpoints together to solve a real problem:

* [**Automated Weekly Report**](/docs/api/weekly-report) — a scheduled digest of last week's traffic, week-over-week change, and top pages and sources.
* [**Find Where Users Drop Off**](/docs/api/funnel-dropoff) — locate the biggest leak in a funnel, then see where the people who abandon go instead.
* [**Compare Channel Performance**](/docs/api/channel-performance) — rank acquisition channels by how well they convert, not just how much traffic they send.
* [**Build a Live Visitor Feed**](/docs/api/live-feed) — poll the events endpoint for a real-time activity stream you can render or alert on.
* [**Export Events to a Warehouse**](/docs/api/export-events) — backfill your full event history and keep it in sync with an incremental job.

## Authentication [#authentication]

All API requests must include authentication using one of the following methods:

### Bearer Token (Recommended) [#bearer-token-recommended]

```bash
Authorization: Bearer your_api_key_here
```

### Query Parameter (Testing Only) [#query-parameter-testing-only]

```bash
?api_key=your_api_key_here
```

<Callout type="warn">
  Query parameters expose API keys in server logs and browser history. Use only for quick testing.
</Callout>

## Generating API Keys [#generating-api-keys]

Rybbit has two kinds of API keys:

* **Organization API keys** (recommended for integrations) — the organization's own credential. They can access every site in the organization and keep working when team members leave. Only organization admins and owners can create and manage them.
* **Personal API keys** — act as you, with exactly your access, including any site restrictions, across every organization you belong to. Best for personal scripts and for connecting MCP clients.

### Organization keys [#organization-keys]

1. Navigate to **Settings → Organization** in your Rybbit dashboard
2. Scroll to the **Organization API Keys** section (visible to admins and owners)
3. Enter a name for the key and click **Create**
4. Copy the key immediately (it won't be shown again)

### Personal keys [#personal-keys]

1. Navigate to **Settings → Account** in your Rybbit dashboard
2. Scroll to the **Personal API Keys** section
3. Enter a name for the key and click **Create**
4. Copy the key immediately (it won't be shown again)

Both kinds support restricting a key to specific permissions when you create it — leave restrictions off for a full-access key.

### Rate Limits (Cloud Only) [#rate-limits-cloud-only]

Requests are limited in two ways: a **burst** limit that is the same on every plan, and a **daily quota** that depends on your plan.

| Plan             | Burst                      | Daily quota             |
| ---------------- | -------------------------- | ----------------------- |
| **Free / Basic** | API keys not available     | —                       |
| **Standard**     | 50 requests per 10 seconds | 5,000 requests per day  |
| **Pro**          | 50 requests per 10 seconds | 25,000 requests per day |

The burst limit is a bucket of 50 requests that refills continuously at 5 requests per second. You can spend all 50 at once, then keep going at 5 per second — so short spikes are fine and there is no window boundary to line up with.

The daily quota resets at **00:00 UTC**.

Requests refused by the burst limit don't count against your daily quota.

#### Which budget a request is charged to [#which-budget-a-request-is-charged-to]

Limits apply per **credential owner**, never per key — creating more keys splits an existing budget rather than adding to it:

| Credential                       | Budget                                                                                      |
| -------------------------------- | ------------------------------------------------------------------------------------------- |
| **Organization key** (`rb_org_`) | The organization's. All of an organization's keys share it.                                 |
| **Personal key**                 | Yours. All of your personal keys share one budget, across every organization you belong to. |
| **OAuth token** (MCP)            | Yours, the same budget as your personal keys.                                               |

A personal key's quota follows the most generous plan among the organizations you belong to.

Self-hosted instances are not rate limited at all — neither tier applies, and no rate limit headers are sent.

#### Reading your remaining budget [#reading-your-remaining-budget]

Analytics and management endpoints report your current budget on every response, so you can pace a client without waiting to be rejected:

| Header                                      | Meaning                                        |
| ------------------------------------------- | ---------------------------------------------- |
| `X-RateLimit-Burst-Limit` / `-Remaining`    | Burst bucket size and tokens left              |
| `X-RateLimit-Burst-Reset`                   | Seconds until the bucket is full again         |
| `X-RateLimit-Daily-Limit` / `-Remaining`    | Daily quota and requests left today            |
| `X-RateLimit-Daily-Reset`                   | Seconds until 00:00 UTC                        |
| `RateLimit-Limit` / `-Remaining` / `-Reset` | Whichever of the two is closest to running out |

Treat these as advisory: a few endpoints resolve credentials outside the standard path and omit them. `Retry-After` on a `429` is always present.

#### When you hit a limit [#when-you-hit-a-limit]

A `429` names the limit you hit and tells you how long to wait, in seconds:

```json
{
  "error": "Rate limit exceeded",
  "scope": "daily",
  "limit": 5000,
  "retryAfter": 34200
}
```

`scope` is `burst` or `daily`, and the same value is in the `Retry-After` header. The difference matters: a `burst` rejection clears in about a second, while a `daily` one lasts until the quota resets. Back off accordingly rather than retrying straight away.

***

## Common Parameters [#common-parameters]

The following parameters are shared across all analytics endpoints.

### Time Parameters [#time-parameters]

All endpoints require date-based, exact datetime, or relative time parameters:

<TypeTable
  type="{
  start_date: {
    description: 'Start date for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD (e.g., &#x22;2024-01-15&#x22;)',
    required: false,
  },
  end_date: {
    description: 'End date for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD (e.g., &#x22;2024-01-31&#x22;)',
    required: false,
  },
  time_zone: {
    description: 'IANA timezone identifier',
    type: 'string',
    typeDescription: 'e.g., &#x22;America/New_York&#x22;, &#x22;Europe/London&#x22;, &#x22;Asia/Tokyo&#x22;. Required with date and exact datetime ranges.',
    required: false,
  },
  start_datetime: {
    description: 'Exact UTC start timestamp for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD HH:mm:ss (e.g., &#x22;2024-01-15 13:00:00&#x22;)',
    required: false,
  },
  end_datetime: {
    description: 'Exact UTC end timestamp for the query period. This boundary is exclusive.',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD HH:mm:ss (e.g., &#x22;2024-01-15 15:00:00&#x22;)',
    required: false,
  },
  past_minutes_start: {
    description: 'Start of relative time range (older boundary)',
    type: 'number',
    typeDescription: 'Minutes ago from now. Must be greater than past_minutes_end.',
    required: false,
  },
  past_minutes_end: {
    description: 'End of relative time range (newer boundary)',
    type: 'number',
    typeDescription: 'Minutes ago from now. Must be less than past_minutes_start.',
    required: false,
  },
}"
/>

**Note:** You must provide either:

* All three date parameters (`start_date`, `end_date`, `time_zone`), OR
* All three exact datetime parameters (`start_datetime`, `end_datetime`, `time_zone`), OR
* Both relative parameters (`past_minutes_start`, `past_minutes_end`)

#### Examples [#examples]

**Date-based query (last 30 days):**

```
?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York
```

**Exact datetime query (8 AM to 10 AM in New York on Jan 15, sent as UTC):**

```
?start_datetime=2024-01-15%2013:00:00&end_datetime=2024-01-15%2015:00:00&time_zone=America/New_York
```

**Relative query (last 60 minutes):**

```
?past_minutes_start=60&past_minutes_end=0
```

### Filter Parameters [#filter-parameters]

The `filters` parameter accepts a JSON-encoded array of filter objects to narrow down your data.

You can also pass `segment_id`, the ID of a [saved segment](/docs/segments), instead of or alongside `filters`. The segment's filters are expanded on the server and ANDed with any `filters` you pass. Use the [Segments endpoints](/docs/api/segments/list) to find IDs. Public and private-link callers can only use segments marked as shown on the public dashboard.

```
?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC&segment_id=12
```

#### Filter Object Structure [#filter-object-structure]

<TypeTable
  type="{
  parameter: {
    description: 'The dimension to filter on',
    type: 'FilterParameter',
    typeDescription: 'See Filter Parameters table below',
    required: true,
  },
  type: {
    description: 'The type of comparison to perform',
    type: 'FilterType',
    typeDescription: '&#x22;equals&#x22; | &#x22;not_equals&#x22; | &#x22;contains&#x22; | &#x22;not_contains&#x22; | &#x22;regex&#x22; | &#x22;not_regex&#x22; | &#x22;greater_than&#x22; | &#x22;less_than&#x22;',
    required: true,
  },
  value: {
    description: 'Array of values to match against',
    type: 'Array<string | number>',
    typeDescription: 'Multiple values are treated as OR conditions',
    required: true,
  },
}"
/>

#### Filter Types [#filter-types]

<TypeTable
  type="{
  equals: {
    description: 'Exact match',
    type: 'string',
    typeDescription: 'Value must exactly match',
  },
  not_equals: {
    description: 'Exclude exact matches',
    type: 'string',
    typeDescription: 'Value must not match',
  },
  contains: {
    description: 'Substring match',
    type: 'string',
    typeDescription: 'Value must contain the substring (uses SQL LIKE %value%)',
  },
  not_contains: {
    description: 'Exclude substring matches',
    type: 'string',
    typeDescription: 'Value must not contain the substring',
  },
  regex: {
    description: 'Regular expression match',
    type: 'string',
    typeDescription: 'Value must match the regex pattern (max 500 characters)',
  },
  not_regex: {
    description: 'Exclude regex matches',
    type: 'string',
    typeDescription: 'Value must not match the regex pattern',
  },
  greater_than: {
    description: 'Numeric greater than',
    type: 'number',
    typeDescription: 'For numeric fields like lat, lon',
  },
  less_than: {
    description: 'Numeric less than',
    type: 'number',
    typeDescription: 'For numeric fields like lat, lon',
  },
}"
/>

#### Available Filter Parameters [#available-filter-parameters]

**Browser & Device**

<TypeTable
  type="{
  browser: {
    description: 'Browser name',
    type: 'string',
    typeDescription: 'e.g., &#x22;Chrome&#x22;, &#x22;Firefox&#x22;, &#x22;Safari&#x22;',
  },
  browser_version: {
    description: 'Browser with version',
    type: 'string',
    typeDescription: 'e.g., &#x22;Chrome 120&#x22;',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
    typeDescription: 'e.g., &#x22;Windows&#x22;, &#x22;macOS&#x22;, &#x22;Linux&#x22;',
  },
  operating_system_version: {
    description: 'OS with version',
    type: 'string',
    typeDescription: 'e.g., &#x22;Windows 10/11&#x22;, &#x22;macOS 14&#x22;',
  },
  device_type: {
    description: 'Device category',
    type: 'string',
    typeDescription: '&#x22;desktop&#x22;, &#x22;mobile&#x22;, &#x22;tablet&#x22;',
  },
  dimensions: {
    description: 'Screen dimensions',
    type: 'string',
    typeDescription: 'e.g., &#x22;1920x1080&#x22;, &#x22;390x844&#x22;',
  },
  language: {
    description: 'Browser language',
    type: 'string',
    typeDescription: 'e.g., &#x22;en-US&#x22;, &#x22;es-ES&#x22;',
  },
}"
/>

**Location**

<TypeTable
  type="{
  country: {
    description: 'Country code',
    type: 'string',
    typeDescription: 'ISO 3166-1 alpha-2 code, e.g., &#x22;US&#x22;, &#x22;GB&#x22;',
  },
  region: {
    description: 'Geographic region/state',
    type: 'string',
    typeDescription: 'e.g., &#x22;California&#x22;, &#x22;England&#x22;',
  },
  city: {
    description: 'City name with region prefix',
    type: 'string',
    typeDescription: 'Format: &#x22;Region-City&#x22;, e.g., &#x22;CA-San Francisco&#x22;',
  },
  timezone: {
    description: 'User timezone',
    type: 'string',
    typeDescription: 'IANA timezone, e.g., &#x22;America/New_York&#x22;',
  },
  lat: {
    description: 'Latitude',
    type: 'number',
    typeDescription: 'Supports greater_than, less_than, equals (with 0.001 tolerance)',
  },
  lon: {
    description: 'Longitude',
    type: 'number',
    typeDescription: 'Supports greater_than, less_than, equals (with 0.001 tolerance)',
  },
}"
/>

**Page & Traffic**

<TypeTable
  type="{
  pathname: {
    description: 'URL pathname',
    type: 'string',
    typeDescription: 'e.g., &#x22;/blog/post-title&#x22;',
  },
  page_title: {
    description: 'HTML page title',
    type: 'string',
  },
  hostname: {
    description: 'Website hostname',
    type: 'string',
    typeDescription: 'e.g., &#x22;example.com&#x22;',
  },
  querystring: {
    description: 'URL query string',
    type: 'string',
    typeDescription: 'e.g., &#x22;?ref=twitter&#x22;',
  },
  referrer: {
    description: 'Referrer domain (without www)',
    type: 'string',
    typeDescription: 'e.g., &#x22;google.com&#x22;, &#x22;twitter.com&#x22;',
  },
  entry_page: {
    description: 'First page in session (landing page)',
    type: 'string',
  },
  exit_page: {
    description: 'Last page in session',
    type: 'string',
  },
  channel: {
    description: 'Marketing channel',
    type: 'string',
    typeDescription: 'e.g., &#x22;Direct&#x22;, &#x22;Organic Search&#x22;, &#x22;Social&#x22;',
  },
}"
/>

**UTM Parameters**

<TypeTable
  type="{
  utm_source: {
    description: 'UTM source parameter',
    type: 'string',
    typeDescription: 'e.g., &#x22;google&#x22;, &#x22;newsletter&#x22;',
  },
  utm_medium: {
    description: 'UTM medium parameter',
    type: 'string',
    typeDescription: 'e.g., &#x22;cpc&#x22;, &#x22;email&#x22;',
  },
  utm_campaign: {
    description: 'UTM campaign parameter',
    type: 'string',
  },
  utm_term: {
    description: 'UTM term parameter',
    type: 'string',
  },
  utm_content: {
    description: 'UTM content parameter',
    type: 'string',
  },
}"
/>

**User & Events**

<TypeTable
  type="{
  user_id: {
    description: 'User identifier',
    type: 'string',
    typeDescription: 'Matches both device fingerprint and custom identified user ID',
  },
  event_name: {
    description: 'Custom event name',
    type: 'string',
    typeDescription: 'Filters to sessions containing the event',
  },
}"
/>

#### Filter Examples [#filter-examples]

<Tabs items="['Single Filter', 'Multiple Filters', 'Contains', 'Regex', 'Numeric', 'URL-encoded']">
  <Tab value="Single Filter">
    ```json
    [
      {
        "parameter": "country",
        "type": "equals",
        "value": ["US"]
      }
    ]
    ```
  </Tab>

  <Tab value="Multiple Filters">
    Multiple filters use AND logic:

    ```json
    [
      {
        "parameter": "country",
        "type": "equals",
        "value": ["US", "CA"]
      },
      {
        "parameter": "device_type",
        "type": "equals",
        "value": ["mobile"]
      }
    ]
    ```
  </Tab>

  <Tab value="Contains">
    Substring match:

    ```json
    [
      {
        "parameter": "pathname",
        "type": "contains",
        "value": ["/blog"]
      }
    ]
    ```
  </Tab>

  <Tab value="Regex">
    Pattern match:

    ```json
    [
      {
        "parameter": "pathname",
        "type": "regex",
        "value": ["^/products/[0-9]+$"]
      }
    ]
    ```
  </Tab>

  <Tab value="Numeric">
    Geolocation comparison:

    ```json
    [
      {
        "parameter": "lat",
        "type": "greater_than",
        "value": ["37.0"]
      },
      {
        "parameter": "lat",
        "type": "less_than",
        "value": ["38.0"]
      }
    ]
    ```
  </Tab>

  <Tab value="URL-encoded">
    ```
    ?filters=%5B%7B%22parameter%22%3A%22country%22%2C%22type%22%3A%22equals%22%2C%22value%22%3A%5B%22US%22%5D%7D%5D
    ```
  </Tab>
</Tabs>

***

## Error Responses [#error-responses]

All endpoints return standard HTTP status codes:

* **200** - Success
* **400** - Bad Request (invalid parameters)
* **401** - Unauthorized (missing or invalid API key)
* **403** - Forbidden (no access to site)
* **404** - Not Found (site doesn't exist)
* **429** - Too Many Requests (rate limit exceeded)
* **500** - Internal Server Error

### Error Response Format [#error-response-format]

```json
{
  "error": "Error message describing what went wrong"
}
```


# Build a Live Visitor Feed (/docs/api/live-feed)





Rybbit doesn't push a websocket stream, but the events endpoint is built for polling: pass a `since_timestamp` and you get only the events that happened after it. This guide builds a self-advancing feed loop you can wire into a dashboard, a terminal ticker, or an alerting rule.

**Endpoints used:**

* [`GET /live-user-count`](/docs/api/overview/live-visitors) — how many visitors are active right now
* [`GET /events`](/docs/api/events/list) — the event stream, polled incrementally

## How incremental polling works [#how-incremental-polling-works]

The events endpoint returns the newest events first. To stream without duplicates, remember the timestamp of the most recent event you've seen and send it as `since_timestamp` on the next request — the API returns only events newer than that, up to 500 per call.

<Steps>
  <Step>
    **Fetch the initial batch** to establish a starting watermark (the newest timestamp).
  </Step>

  <Step>
    **On an interval, request events `since_timestamp`** = your watermark.
  </Step>

  <Step>
    **Process the new events** (print, render, alert) and advance the watermark to the newest one returned.
  </Step>
</Steps>

<Callout type="info">
  `since_timestamp` returns up to **500** events per call. If you expect more than 500 events between polls (a very high-traffic site with a long interval), poll more frequently so each batch stays under the cap.
</Callout>

## Full script [#full-script]

A Node script that prints a live count plus a rolling feed of activity. The same loop drives a browser dashboard — just replace `console.log` with DOM updates.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="live-feed.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const POLL_MS = 10000; // every 10 seconds

    async function get(path, params = {}) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    async function liveCount() {
      const { count } = await get('/live-user-count', { minutes: 5 });
      return count;
    }

    function describe(e) {
      const where = e.city ? `${e.city}, ${e.country}` : e.country || 'Unknown';
      if (e.type === 'pageview')     return `👀 viewed ${e.pathname} — ${where}`;
      if (e.type === 'custom_event') return `⚡ ${e.event_name} (${e.pathname}) — ${where}`;
      if (e.type === 'outbound')     return `↗️  left via ${e.pathname} — ${where}`;
      return `• ${e.type} — ${where}`;
    }

    let watermark = null; // ISO timestamp of the newest event we've shown

    async function poll() {
      try {
        const params = watermark ? { since_timestamp: watermark } : { page_size: 20 };
        const [{ data: events }, count] = await Promise.all([get('/events', params), liveCount()]);

        // Events come back newest-first; show oldest-first so the feed reads top-to-bottom
        for (const e of [...events].reverse()) {
          console.log(`[${new Date(e.timestamp).toLocaleTimeString()}] ${describe(e)}`);
        }
        if (events.length) watermark = events[0].timestamp; // newest event becomes the new watermark

        process.stdout.write(`\n🟢 ${count} visitors online\n`);
      } catch (err) {
        console.error('poll error:', err.message);
      }
    }

    console.log('Starting live feed… (Ctrl+C to stop)');
    poll();
    setInterval(poll, POLL_MS);
    ```
  </Tab>

  <Tab value="Python">
    ```python title="live_feed.py"
    import os, time
    from datetime import datetime
    import requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    POLL_SECONDS = 10

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def get(path, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def live_count():
        return get("/live-user-count", minutes=5)["count"]


    def describe(e):
        where = f'{e["city"]}, {e["country"]}' if e.get("city") else e.get("country") or "Unknown"
        if e["type"] == "pageview":
            return f'👀 viewed {e["pathname"]} — {where}'
        if e["type"] == "custom_event":
            return f'⚡ {e["event_name"]} ({e["pathname"]}) — {where}'
        if e["type"] == "outbound":
            return f'↗️  left via {e["pathname"]} — {where}'
        return f'• {e["type"]} — {where}'


    watermark = None  # ISO timestamp of the newest event we've shown

    print("Starting live feed… (Ctrl+C to stop)")
    while True:
        try:
            params = {"since_timestamp": watermark} if watermark else {"page_size": 20}
            events = get("/events", **params)["data"]

            # Events come back newest-first; show oldest-first so the feed reads top-to-bottom
            for e in reversed(events):
                ts = datetime.fromisoformat(e["timestamp"].replace("Z", "+00:00")).strftime("%H:%M:%S")
                print(f"[{ts}] {describe(e)}")
            if events:
                watermark = events[0]["timestamp"]  # newest event becomes the new watermark

            print(f"\n🟢 {live_count()} visitors online\n")
        except Exception as err:
            print(f"poll error: {err}")
        time.sleep(POLL_SECONDS)
    ```
  </Tab>
</Tabs>

## Example output [#example-output]

```text
Starting live feed… (Ctrl+C to stop)
[14:22:01] 👀 viewed /pricing — San Francisco, US
[14:22:03] ⚡ signup (/signup) — London, GB
[14:22:05] ↗️  left via /docs — Berlin, DE

🟢 42 visitors online
```

## Turn it into an alert [#turn-it-into-an-alert]

Because each poll hands you the raw events, you can act on them instead of just printing. For example, ping a channel whenever someone hits your enterprise pricing page:

<Tabs items="['JavaScript']">
  <Tab value="JavaScript">
    ```javascript title="React to specific events"
    for (const e of events) {
      if (e.type === 'pageview' && e.pathname === '/enterprise') {
        await fetch(process.env.SLACK_WEBHOOK, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            text: `🏢 Enterprise page visit from ${e.city || e.country} (${e.referrer || 'direct'})`,
          }),
        });
      }
    }
    ```
  </Tab>
</Tabs>

<Callout type="warn">
  **Mind the daily quota.** On Rybbit Cloud, a continuous poll is measured against your plan's daily quota (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only)), not just its per-second rate. A 10-second poll running around the clock is 8,640 requests/day — over the Standard quota of 5,000, and 17,280 with the live-count call added. Poll every 20-30 seconds, or only while someone is actually watching the page, and check `X-RateLimit-Daily-Remaining` to see where you stand. Self-hosted instances are not rate limited.
</Callout>

## Next steps [#next-steps]

* [Events API reference](/docs/api/events/list) — full event object fields, plus `before_timestamp` for scrolling backwards through history.
* [Export Raw Events to Your Warehouse](/docs/api/export-events) — the same `since_timestamp` mechanism, used for durable incremental syncs instead of a live view.


# Sending Events (/docs/api/sending-events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/track
    ```

    Track pageviews, custom events, performance, and errors from server-side applications, mobile apps, or any platform. An API key is optional but recommended for server-side tracking — it bypasses bot detection and domain validation. IP addresses are resolved to geolocation and user agents are parsed for browser/OS/device info.

    ### Request Body [#request-body]

    All parameters are sent in the request body as JSON.

    <TypeTable
      type="{
  site_id: {
    description: 'Your site ID',
    type: 'string',
    required: true,
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;performance&#x22; | &#x22;outbound&#x22; | &#x22;error&#x22;',
    default: 'pageview',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  hostname: {
    description: 'Domain name',
    type: 'string',
    typeDescription: 'Max 253 chars',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
    typeDescription: 'Max 512 chars',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  user_id: {
    description: 'Custom user identifier',
    type: 'string',
    typeDescription: 'Max 255 chars',
  },
  user_agent: {
    description: 'Custom user agent string - will be parsed for browser/OS/device info',
    type: 'string',
    typeDescription: 'Max 512 chars',
  },
  ip_address: {
    description: 'Custom IP for geolocation - will be resolved to location data',
    type: 'string',
    typeDescription: 'Valid IPv4 or IPv6 address',
  },
  querystring: {
    description: 'Query parameters',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  language: {
    description: 'Language code',
    type: 'string',
    typeDescription: 'e.g., &#x22;en&#x22;, &#x22;es&#x22;, &#x22;fr&#x22;',
  },
  screenWidth: {
    description: 'Screen width in logical pixels (density-independent pixels)',
    type: 'number',
  },
  screenHeight: {
    description: 'Screen height in logical pixels (density-independent pixels)',
    type: 'number',
  },
  event_name: {
    description: 'Event name (required for custom events)',
    type: 'string',
    typeDescription: 'Max 256 chars',
  },
  properties: {
    description: 'JSON string with event data (for custom events, outbound, error)',
    type: 'string',
    typeDescription: 'Max 2048 chars (4096 for error events)',
  },
  feature_flags: {
    description: 'Optional map of feature flag keys to assigned values. Useful for server-side flag evaluation and filtering analytics by flag value.',
    type: 'Record<string, string>',
    typeDescription: 'Keys max 100 chars, values max 2048 chars',
  },
}"
    />

    #### Pageview [#pageview]

    Standard page view tracking. Set `type: "pageview"` (default).

    #### Custom Event [#custom-event]

    Track custom events with optional properties. Set `type: "custom_event"`.

    <TypeTable
      type="{
  event_name: {
    description: 'Name of the custom event',
    type: 'string',
    typeDescription: 'Max 256 chars',
    required: true,
  },
  properties: {
    description: 'Event data as JSON string',
    type: 'string',
    typeDescription: 'Valid JSON, max 2048 chars',
  },
}"
    />

    #### Performance [#performance]

    Track Core Web Vitals. Set `type: "performance"`.

    <TypeTable
      type="{
  lcp: {
    description: 'Largest Contentful Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  cls: {
    description: 'Cumulative Layout Shift score',
    type: 'number',
    typeDescription: 'nullable, typically 0-1',
  },
  inp: {
    description: 'Interaction to Next Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  fcp: {
    description: 'First Contentful Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  ttfb: {
    description: 'Time to First Byte in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
}"
    />

    #### Outbound [#outbound]

    Track outbound link clicks. Set `type: "outbound"`. Pass details in the `properties` JSON string.

    <TypeTable
      type="{
  url: {
    description: 'Destination URL',
    type: 'string',
    required: true,
  },
  text: {
    description: 'Link text content',
    type: 'string',
  },
  target: {
    description: 'Link target attribute',
    type: 'string',
    typeDescription: 'e.g., &#x22;_blank&#x22;, &#x22;_self&#x22;',
  },
}"
    />

    #### Error [#error]

    Track JavaScript errors. Set `type: "error"`. `event_name` is the error type and `properties` carries the error details as a JSON string.

    <TypeTable
      type="{
  message: {
    description: 'Error message',
    type: 'string',
    typeDescription: 'Max 500 chars',
    required: true,
  },
  stack: {
    description: 'Stack trace',
    type: 'string',
    typeDescription: 'Max 2000 chars',
  },
  fileName: {
    description: 'File where error occurred',
    type: 'string',
  },
  lineNumber: {
    description: 'Line number',
    type: 'number',
  },
  columnNumber: {
    description: 'Column number',
    type: 'number',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the event was accepted',
    type: 'boolean',
  },
}"
    />

    ### Rate Limiting [#rate-limiting]

    API keys are limited to **500 requests per 10 minutes**. Exceeding the limit returns a `429` status code.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/track" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "site_id": "1",
            "type": "custom_event",
            "pathname": "/checkout",
            "event_name": "purchase",
            "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch('https://app.rybbit.io/api/track', {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer your_api_key_here',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            site_id: '1',
            type: 'custom_event',
            pathname: '/checkout',
            event_name: 'purchase',
            properties: JSON.stringify({ amount: 99.99, currency: 'USD' })
          })
        });

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests
        import json

        response = requests.post(
            'https://app.rybbit.io/api/track',
            json={
                'site_id': '1',
                'type': 'custom_event',
                'pathname': '/checkout',
                'event_name': 'purchase',
                'properties': json.dumps({'amount': 99.99, 'currency': 'USD'})
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'site_id' => '1',
            'type' => 'custom_event',
            'pathname' => '/checkout',
            'event_name' => 'purchase',
            'properties' => json_encode(['amount' => 99.99, 'currency' => 'USD'])
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/track');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/track')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          site_id: '1',
          type: 'custom_event',
          pathname: '/checkout',
          event_name: 'purchase',
          properties: { amount: 99.99, currency: 'USD' }.to_json
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "site_id":    "1",
            "type":       "custom_event",
            "pathname":   "/checkout",
            "event_name": "purchase",
            "properties": `{"amount": 99.99, "currency": "USD"}`,
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/track", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "site_id": "1",
            "type": "custom_event",
            "pathname": "/checkout",
            "event_name": "purchase",
            "properties": r#"{"amount": 99.99, "currency": "USD"}"#
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/track")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "site_id": "1",
          "type": "custom_event",
          "pathname": "/checkout",
          "event_name": "purchase",
          "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/track"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            site_id = "1",
            type = "custom_event",
            pathname = "/checkout",
            event_name = "purchase",
            properties = JsonSerializer.Serialize(new { amount = 99.99, currency = "USD" })
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/track", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Success"
    {
      "success": true
    }
    ```

    ```json title="Error"
    {
      "success": false,
      "error": "Invalid payload",
      "details": {
        "fieldErrors": {},
        "formErrors": ["Custom events require event_name"]
      }
    }
    ```
  </div>
</div>


# Automated Weekly Report (/docs/api/weekly-report)





This guide builds a script you can run on a schedule (a cron job, GitHub Action, or serverless function) that pulls last week's numbers, compares them to the week before, and posts a digest to Slack, email, or anywhere else.

**Endpoints used:**

* [`GET /overview`](/docs/api/overview/overview) — headline metrics for a date range
* [`GET /metric`](/docs/api/overview/metric) — top pages and traffic sources

<Callout type="info">
  Every analytics endpoint takes the same [time parameters](/docs/api/getting-started#time-parameters). The trick behind any comparison report is simply calling the same endpoint twice with two adjacent date ranges.
</Callout>

## The workflow [#the-workflow]

<Steps>
  <Step>
    **Fetch this week's overview** for the last 7 days.
  </Step>

  <Step>
    **Fetch last week's overview** for the 7 days before that, so you can compute the change.
  </Step>

  <Step>
    **Fetch top pages and top sources** from the `metric` endpoint to add context.
  </Step>

  <Step>
    **Format and deliver** the digest.
  </Step>
</Steps>

## Full script [#full-script]

This example posts a formatted message to a Slack incoming webhook, but the `buildReport` function returns plain data you can route anywhere.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="weekly-report.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const SLACK_WEBHOOK = process.env.SLACK_WEBHOOK;
    const TZ = 'America/New_York';

    // Helper: format a Date as YYYY-MM-DD
    const ymd = (d) => d.toISOString().slice(0, 10);

    async function get(path, params) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${API_KEY}` },
      });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    async function overview(start, end) {
      const { data } = await get('/overview', {
        start_date: ymd(start),
        end_date: ymd(end),
        time_zone: TZ,
      });
      return data;
    }

    async function topMetric(parameter, start, end, limit = 5) {
      const { data } = await get('/metric', {
        parameter,
        start_date: ymd(start),
        end_date: ymd(end),
        time_zone: TZ,
        limit,
      });
      return data.data; // metric nests results under data.data
    }

    function pctChange(current, previous) {
      if (!previous) return null;
      return ((current - previous) / previous) * 100;
    }

    async function buildReport() {
      const now = new Date();
      const thisWeekStart = new Date(now); thisWeekStart.setDate(now.getDate() - 7);
      const lastWeekEnd   = new Date(now); lastWeekEnd.setDate(now.getDate() - 8);
      const lastWeekStart = new Date(now); lastWeekStart.setDate(now.getDate() - 14);

      const [thisWeek, lastWeek, topPages, topSources] = await Promise.all([
        overview(thisWeekStart, now),
        overview(lastWeekStart, lastWeekEnd),
        topMetric('pathname', thisWeekStart, now),
        topMetric('referrer', thisWeekStart, now),
      ]);

      return {
        sessions: { value: thisWeek.sessions, change: pctChange(thisWeek.sessions, lastWeek.sessions) },
        users:    { value: thisWeek.users,    change: pctChange(thisWeek.users, lastWeek.users) },
        pageviews:{ value: thisWeek.pageviews, change: pctChange(thisWeek.pageviews, lastWeek.pageviews) },
        bounceRate: thisWeek.bounce_rate,
        topPages,
        topSources,
      };
    }

    function arrow(change) {
      if (change === null) return '';
      const sign = change >= 0 ? '▲' : '▼';
      return ` ${sign} ${Math.abs(change).toFixed(1)}%`;
    }

    async function postToSlack(r) {
      const lines = [
        `*📊 Weekly Analytics Report*`,
        ``,
        `• Sessions: *${r.sessions.value.toLocaleString()}*${arrow(r.sessions.change)}`,
        `• Unique users: *${r.users.value.toLocaleString()}*${arrow(r.users.change)}`,
        `• Pageviews: *${r.pageviews.value.toLocaleString()}*${arrow(r.pageviews.change)}`,
        `• Bounce rate: *${r.bounceRate.toFixed(1)}%*`,
        ``,
        `*Top pages*`,
        ...r.topPages.map((p) => `   ${p.value} — ${p.count.toLocaleString()}`),
        ``,
        `*Top sources*`,
        ...r.topSources.map((s) => `   ${s.value || 'Direct'} — ${s.count.toLocaleString()}`),
      ];
      await fetch(SLACK_WEBHOOK, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text: lines.join('\n') }),
      });
    }

    buildReport().then(postToSlack).catch(console.error);
    ```
  </Tab>

  <Tab value="Python">
    ```python title="weekly_report.py"
    import os
    from datetime import datetime, timedelta
    import requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    SLACK_WEBHOOK = os.environ["SLACK_WEBHOOK"]
    TZ = "America/New_York"

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def ymd(d: datetime) -> str:
        return d.strftime("%Y-%m-%d")


    def get(path: str, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def overview(start, end):
        return get("/overview", start_date=ymd(start), end_date=ymd(end), time_zone=TZ)["data"]


    def top_metric(parameter, start, end, limit=5):
        # metric nests results under data.data
        return get("/metric", parameter=parameter, start_date=ymd(start),
                   end_date=ymd(end), time_zone=TZ, limit=limit)["data"]["data"]


    def pct_change(current, previous):
        return None if not previous else (current - previous) / previous * 100


    def build_report():
        now = datetime.utcnow()
        this_start = now - timedelta(days=7)
        last_end = now - timedelta(days=8)
        last_start = now - timedelta(days=14)

        this_week = overview(this_start, now)
        last_week = overview(last_start, last_end)

        return {
            "sessions": (this_week["sessions"], pct_change(this_week["sessions"], last_week["sessions"])),
            "users": (this_week["users"], pct_change(this_week["users"], last_week["users"])),
            "pageviews": (this_week["pageviews"], pct_change(this_week["pageviews"], last_week["pageviews"])),
            "bounce_rate": this_week["bounce_rate"],
            "top_pages": top_metric("pathname", this_start, now),
            "top_sources": top_metric("referrer", this_start, now),
        }


    def arrow(change):
        if change is None:
            return ""
        return f" {'▲' if change >= 0 else '▼'} {abs(change):.1f}%"


    def post_to_slack(r):
        lines = [
            "*📊 Weekly Analytics Report*", "",
            f"• Sessions: *{r['sessions'][0]:,}*{arrow(r['sessions'][1])}",
            f"• Unique users: *{r['users'][0]:,}*{arrow(r['users'][1])}",
            f"• Pageviews: *{r['pageviews'][0]:,}*{arrow(r['pageviews'][1])}",
            f"• Bounce rate: *{r['bounce_rate']:.1f}%*", "",
            "*Top pages*",
            *[f"   {p['value']} — {p['count']:,}" for p in r["top_pages"]], "",
            "*Top sources*",
            *[f"   {s['value'] or 'Direct'} — {s['count']:,}" for s in r["top_sources"]],
        ]
        requests.post(SLACK_WEBHOOK, json={"text": "\n".join(lines)})


    post_to_slack(build_report())
    ```
  </Tab>
</Tabs>

## Example output [#example-output]

```text
📊 Weekly Analytics Report

• Sessions: 15,420 ▲ 12.3%
• Unique users: 12,847 ▲ 9.8%
• Pageviews: 48,933 ▼ 2.1%
• Bounce rate: 42.8%

Top pages
   / — 8,230
   /pricing — 3,120
   /blog/getting-started — 1,940

Top sources
   google.com — 6,410
   Direct — 4,220
   twitter.com — 1,180
```

## Schedule it [#schedule-it]

Run the script every Monday morning with cron:

```bash title="crontab -e"
# Every Monday at 9:00 AM
0 9 * * 1 RYBBIT_API_KEY=xxx SLACK_WEBHOOK=https://hooks.slack.com/... node /path/to/weekly-report.js
```

<Callout type="info">
  **Want a richer report?** The same pattern extends naturally. Add `topMetric('channel', ...)` for marketing channels, `topMetric('country', ...)` for geography, or call the [`time-series` endpoint](/docs/api/overview/time-series) with `bucket=day` to attach a 7-point trend line.
</Callout>

## Next steps [#next-steps]

* [Compare Marketing Channel Performance](/docs/api/channel-performance) — go beyond traffic counts and rank sources by how well they convert.
* [Export Raw Events to Your Warehouse](/docs/api/export-events) — if you'd rather build reports in your own BI tool.


# Dashboard Embed (/docs/embeds/dashboard)





The dashboard embed lets you place the main Rybbit analytics dashboard on another site with a self-contained iframe. Dashboard embeds use private-link routes with `embed=true`.

## Try It Out [#try-it-out]

Configure the private-link dashboard embed URL below. The generated snippet uses the same private-link route created in the Rybbit dashboard.

<DashboardEmbedDemo />

## Requirements [#requirements]

Dashboard embeds require a generated private link. The private link key is included in the route, for example `/{siteId}/{privateLinkKey}/main`.

Unlike [Widget Embeds](/docs/embeds/widget), dashboard embeds expose the full read-only analytics dashboard, not just the compact live visitor widget.

<Callout type="warn">
  Private links are not listed publicly, but anyone with the private link can view the dashboard. Treat the iframe URL like a shareable read-only secret.
</Callout>

## Setup [#setup]

1. Open your site in the Rybbit dashboard and click the settings icon.
2. Go to the **Dashboard Embed** tab.
3. Generate a private link if one does not already exist.
4. Choose the embed theme: light, dark, or system.
5. Choose whether to hide the dashboard sidebar.
6. Copy the generated `<iframe>` snippet and paste it anywhere on your site.

## Appearance [#appearance]

* **Theme**: `light`, `dark`, or `system`. `system` follows the viewer's operating system color-scheme preference.
* **Hide sidebar**: removes the dashboard sidebar and keeps viewers on the main dashboard page.
* **Footer**: the Rybbit footer is hidden automatically in embed mode.

## Example [#example]

```html
<iframe
  src="https://app.rybbit.io/YOUR_SITE_ID/YOUR_PRIVATE_LINK_KEY/main?embed=true&theme=system&hideSidebar=true"
  style="border: 0; width: 100%; height: 720px;"
  loading="lazy"
  title="Analytics dashboard"
></iframe>
```

If you self-host Rybbit, replace `app.rybbit.io` with your own domain.

## URL Parameters [#url-parameters]

| Parameter     | Values                    | Description                                                               |
| ------------- | ------------------------- | ------------------------------------------------------------------------- |
| `embed`       | `true`                    | Enables embed mode                                                        |
| `theme`       | `light`, `dark`, `system` | Sets the embedded dashboard color scheme. Defaults to `system`            |
| `hideSidebar` | `true`, `false`           | Hides the dashboard sidebar and keeps visitors on the main dashboard page |

When `hideSidebar=true`, only the main dashboard page is shown in the iframe. Leave it off if you want viewers to use the dashboard sidebar to navigate other analytics pages allowed by the private link.

The private key is part of the path, not a query parameter: `/{siteId}/{privateLinkKey}/main?embed=true`.


# Widget Embeds (/docs/embeds/widget)





Widget Embeds let you place a compact live visitor widget on another site with a self-contained iframe. There is no script tag, no JavaScript on your site, and no dependency on the Rybbit tracking script.

## Try It [#try-it]

Configure the widget below to see how it'll look. The preview shows live data from [demo.rybbit.com](https://demo.rybbit.com).

<EmbedWidgetDemo />

## Requirements [#requirements]

The widget needs a public read-only data endpoint, so you must enable **Widget Embeds** on the site. This is separate from **Public Analytics**. Turning it on only exposes the live count, time series, and top countries to the widget endpoint, not your full dashboard.

<Callout type="info">
  Enabling Widget Embeds does **not** make your dashboard public. Only the data shown in the widget itself (visitor count, per-minute / per-hour / per-day series, top 5 countries) is accessible; no individual sessions, events, pages, or referrers are exposed.
</Callout>

## Setup [#setup]

1. Open your site in the Rybbit dashboard and click the settings icon.
2. Go to the **Widget Embeds** tab.
3. Toggle **Widget Enabled** on.
4. Pick your options: variant, time window, theme, accent color, and display settings.
5. Copy the generated `<iframe>` snippet and paste it anywhere on your site.

## Variants [#variants]

### Card [#card]

A self-contained dashboard card showing the live count, an optional bar chart of users over time, and an optional list of top countries.

| Option        | Values                         | Default | Description                                              |
| ------------- | ------------------------------ | ------- | -------------------------------------------------------- |
| Time window   | 30 minutes / 24 hours / 7 days | 30 min  | Window the count and chart cover                         |
| Bar chart     | on / off                       | on      | Show a bar chart bucketed per minute / hour / day        |
| Top countries | on / off                       | on      | List the top 5 countries in the window                   |
| Width         | 240-800 px                     | 360 px  | Iframe width; use `max-width: 100%` for responsive sites |

### Inline Pill [#inline-pill]

A compact pill that fits inline with your site's chrome, such as in a header or footer. It shows the pulsing dot, the live count over the last 30 minutes, and the Rybbit logo.

## Appearance [#appearance]

* **Theme**: `dark` or `light`. The widget background is transparent, so rounded-corner edges blend into whatever sits behind the iframe.
* **Accent color**: any hex color. Used for the pulsing live-indicator dot and the bar-chart bars. Defaults to Rybbit emerald.

## Example [#example]

```html
<iframe
  src="https://app.rybbit.io/widget/YOUR_SITE_ID?variant=card&theme=dark&minutes=30&chart=true&countries=true"
  style="border: 0; width: 360px; height: 390px; max-width: 100%;"
  loading="lazy"
  title="Live visitors"
></iframe>
```

If you self-host Rybbit, replace `app.rybbit.io` with your own domain.

## URL Parameters [#url-parameters]

You don't usually need to build the URL by hand because the dashboard generates the snippet for you, but the widget URL accepts these parameters:

| Parameter   | Values                                 | Description                               |
| ----------- | -------------------------------------- | ----------------------------------------- |
| `variant`   | `card`, `inline`                       | Layout variant                            |
| `theme`     | `dark`, `light`                        | Color scheme                              |
| `accent`    | 6-character hex, no `#`, e.g. `10b981` | Pulse / bar color                         |
| `minutes`   | `30`, `1440`, `10080`                  | Time window in minutes, card variant only |
| `chart`     | `true`, `false`                        | Show the bar chart, card variant only     |
| `countries` | `true`, `false`                        | Show top countries, card variant only     |

## Caching [#caching]

The widget HTML and the underlying stats endpoint are both cached for 60 seconds on the server, so embedding the widget on a high-traffic page won't put pressure on your Rybbit instance. The visible count refreshes once per minute.


# Errors (/docs/feature-guides/errors)



The Errors tab shows JavaScript errors occurring on your website, helping you identify and fix bugs that affect user experience.

## Enabling Error Tracking [#enabling-error-tracking]

Enable error tracking in your [site settings](/docs/site-settings).

## Error Information [#error-information]

For each error, you'll see:

* **Error Type** - ReferenceError, TypeError, SyntaxError, NetworkError, etc.
* **Error Message** - The specific error message
* **Stack Trace** - The chain of function calls that led to the error
* **Affected Sessions** - Number of unique sessions in which this error occurred
* **Occurrence Count** - How many times the error was triggered
  Expanding an error shows its individual occurrences, including the timestamp and page for each event.
* **Browser & Device** - Which environments experience this error

## Using Error Data [#using-error-data]

* **Prioritize by impact** - Fix errors affecting the most users first
* **Monitor after deployments** - Watch for new errors after releasing code
* **Debug user reports** - Find the exact technical issue when users report problems
* **Track third-party issues** - Identify when external integrations are malfunctioning


# Events (/docs/feature-guides/events)



The Events tab shows custom events tracked on your website.

## Setting Up Events [#setting-up-events]

See the [Track Events guide](/docs/track-events) for implementation details.

## Events Page [#events-page]

The events page includes:

* **Events Chart** - Visualize event trends over time
* **Event Log** - Recent individual event occurrences (click any row to open a details sheet)

The **Custom Events List** — all tracked events with counts — lives in the Events section of the main dashboard.

## Event Metrics [#event-metrics]

For each event in the Custom Events List:

* **Event Name** - The name you assigned to the event
* **Count** - Total times triggered in the selected period
* **Percentage** - Share of total events

## Event Properties [#event-properties]

In the Custom Events List, click the expand arrow on any event to view its properties. Properties show the key-value pairs attached to events, helping you understand event context (e.g., which product was purchased, what button was clicked).

## Filtering [#filtering]

* Click any event name to filter the dashboard to sessions containing that event
* Use the filter panel to combine event filters with other dimensions
* Filter by time range to analyze event trends


# Globe (/docs/feature-guides/globe)



The Globe tab shows where your visitors connect from on an interactive map.

## View Modes [#view-modes]

### 2D Map [#2d-map]

* **Timeline** - View sessions by timeframe, click individual sessions for details
* **Coordinates** - Sessions as dots with color intensity showing traffic volume
* **Countries** - Countries highlighted by traffic volume
* **Subdivisions** - Granular view by national subdivisions

### 3D Globe [#3d-globe]

Same four views as 2D, plus:

* Rotate by dragging
* Zoom in and out
* Traffic hotspots glow

The 3D view requires a Mapbox API token. Self-hosted installations need `MAPBOX_TOKEN` in environment variables. Cloud includes this automatically.

## Time Controls [#time-controls]

Pick date ranges to see how geographic distribution changes over time.

## Filtering [#filtering]

Apply the same filters as the main dashboard to see geographic distribution for specific segments.


# User Journeys (/docs/feature-guides/journeys)





<img alt="User Journeys Dashboard" src="__img0" />

User journeys show the actual paths people take as they move through your website, revealing how they flow from page to page.

## Reading the Visualization [#reading-the-visualization]

### Nodes [#nodes]

Each bar represents a page or event. Its height indicates how many users reached that point.

### Connections [#connections]

Lines between nodes show user flow. Thicker connections mean more users took that path.

### Flow Direction [#flow-direction]

The visualization flows left to right, showing progression through time.

## Key Patterns to Look For [#key-patterns-to-look-for]

* **Happy Path** - The most common route to conversion
* **Drop-off Points** - Where many users enter but few continue
* **Backtracking** - Users moving backward, often indicating confusion
* **Alternative Routes** - Unexpected paths to important pages

## Using Journey Insights [#using-journey-insights]

* **Simplify complex paths** - Create shortcuts to important pages
* **Fix drop-off points** - Investigate why users leave at certain pages
* **Amplify successful paths** - Make high-converting routes easier to follow
* **Reduce backtracking** - Improve navigation where users get lost

## Analysis Types [#analysis-types]

* **Entry point analysis** - Where do users go from a specific page?
* **Goal-based analysis** - How did converting users get there?
* **Full journey mapping** - Overall flow from entry to exit


# Main Dashboard (/docs/feature-guides/main-tab)





<img alt="Main Dashboard" src="__img0" />

The main dashboard is your home base in Rybbit Analytics, showing all key metrics at a glance.

## Top Metrics [#top-metrics]

* **Unique Users** - Different people who visited your site
* **Total Sessions** - Number of visits (30-minute inactivity starts a new session)
* **Total Pageviews** - Every page load from every visitor
* **Bounce Rate** - Percentage of single-page sessions
* **Pages Per Session** - Average pages viewed per visit
* **Session Duration** - Average time spent per visit

## Time Controls [#time-controls]

Select date ranges: Today, Yesterday, Last 7/30/60 days, This Week, This Month, All Time, or a custom range.

## Filters [#filters]

Combine filters for granular analysis:

* Device type, browser, OS
* Country, city
* Referrer, UTM parameters
* Custom event properties

A set of filters you use often can be saved as a [segment](/docs/segments) from the **Segments** tab of the Filter button, then applied to any report with one click.

## Main Chart [#main-chart]

Shows your selected metric over time. Click the metric selector to switch between Users, Sessions, Pageviews, Bounce Rate, Pages Per Session, or Session Duration.

## Traffic Sources [#traffic-sources]

See where your traffic comes from:

* **Direct** - Typed URL or bookmarks
* **Search** - Google, Bing, DuckDuckGo, etc.
* **Social** - Twitter, Facebook, LinkedIn, Reddit
* **Referral** - Other websites

Click any source to filter the entire dashboard to that traffic.

## UTM Parameters [#utm-parameters]

View campaign data: utm\_campaign, utm\_source, utm\_medium, utm\_term, utm\_content.

## Additional Breakdowns [#additional-breakdowns]

* **Top Pages** - Most visited URLs with pageviews, visitors, time on page, and bounce rate
* **Entry/Exit Pages** - Where visits begin and end
* **Devices & Browsers** - Desktop/mobile/tablet split, browser and OS breakdown
* **Screen Resolutions** - What sizes your visitors use
* **Geographic Data** - Countries and regions
* **Custom Events** - Click any event to filter to sessions containing it


# Pages (/docs/feature-guides/pages-tab)





<img alt="Pages Dashboard" src="__img0" />

The Pages tab shows detailed analytics for every URL on your site.

## Page Metrics [#page-metrics]

Each page displays:

* **Page URL** - The full path
* **Sessions** - Number of sessions that viewed this page
* **Average Time on Page** - How long visitors spend there

## Filtering [#filtering]

Use the same filters as the main dashboard to analyze specific segments:

* Mobile users from social media
* Desktop users who converted
* Users who triggered specific events

## Identifying Issues [#identifying-issues]

* Scan for pages with low time on page to find content that isn't engaging
* Look for pages with few sessions to find underperforming pages
* Compare entry pages to see which content attracts traffic


# Performance (/docs/feature-guides/performance)





<img alt="Performance Dashboard" src="__img0" />

The Performance tab tracks Core Web Vitals from real user data.

## Enabling Performance Tracking [#enabling-performance-tracking]

Enable Web Vitals in your [site settings](/docs/site-settings).

## Web Vitals [#web-vitals]

### Largest Contentful Paint (LCP) [#largest-contentful-paint-lcp]

How long the main content takes to load.

* **Good**: Under 2.5 seconds
* **Needs Improvement**: 2.5-4 seconds
* **Poor**: Over 4 seconds

### Cumulative Layout Shift (CLS) [#cumulative-layout-shift-cls]

How much content jumps around while loading.

* **Good**: Under 0.1
* **Needs Improvement**: 0.1-0.25
* **Poor**: Over 0.25

### Interaction to Next Paint (INP) [#interaction-to-next-paint-inp]

How quickly your site responds to user interactions.

* **Good**: Under 200ms
* **Needs Improvement**: 200-500ms
* **Poor**: Over 500ms

### First Contentful Paint (FCP) [#first-contentful-paint-fcp]

How long until the first content appears.

* **Good**: Under 1.8 seconds
* **Needs Improvement**: 1.8-3 seconds
* **Poor**: Over 3 seconds

### Time to First Byte (TTFB) [#time-to-first-byte-ttfb]

How long until the server responds.

* **Good**: Under 800ms
* **Needs Improvement**: 800-1800ms
* **Poor**: Over 1800ms

## Percentile Selector [#percentile-selector]

Choose which percentile to view (p50, p75, p90, p99). The p75 is commonly used for Core Web Vitals assessment.

## Comparison [#comparison]

Each metric shows the change from the previous period, with green indicating improvement and red indicating degradation.

## Breakdowns [#breakdowns]

* **By Page** - Find your slowest pages
* **By Device** - Compare mobile vs desktop performance
* **By Browser** - Identify browser-specific issues
* **By Country** - See geographic performance differences


# Retention (/docs/feature-guides/retention)





<img alt="Retention Dashboard" src="__img0" />

Retention analysis shows how many users come back to your site over time, revealing whether users find lasting value.

## Understanding Cohorts [#understanding-cohorts]

A cohort is a group of users who share a common start date. For example, all users who first visited on January 15th form one cohort.

## Reading the Retention Table [#reading-the-retention-table]

### Rows [#rows]

Each row is a different cohort, grouped by first visit date.

### Columns [#columns]

* **Day/Week 0** - Starting point (always 100%)
* **Day/Week 1, 2, 3...** - Users who returned after that period

### Numbers [#numbers]

Percentages show what portion of the original cohort returned. 40% in the "Day 7" column means 40% of users came back after a week.

### Color Coding [#color-coding]

* Lighter colors = higher retention
* Darker colors = more drop-off

## Key Insights [#key-insights]

* **Day 1 retention** - Did users find enough value to return the next day?
* **Day 7 retention** - Did users integrate your product into their routine?
* **Day 30 retention** - Have users formed a habit?

## Common Patterns [#common-patterns]

* **Cliff drop** - Sharp decline in first few days indicates onboarding issues
* **Steady decline** - Gradual drop suggests novelty wearing off
* **Plateau** - When retention levels off, you've found your core users

## Note on User ID Salting [#note-on-user-id-salting]

If [User ID Salting](/docs/site-settings) is enabled, retention beyond 24 hours becomes less accurate since user identifiers reset daily.


# Session Replay (/docs/feature-guides/session-replay)





<img alt="Session Replay" src="__img0" />

Session replay lets you watch anonymized recordings of real user sessions, showing mouse movements, clicks, scrolls, and page navigation.

## Enabling Session Replay [#enabling-session-replay]

Enable session replay in your [site settings](/docs/site-settings). The tracking script picks the setting up automatically — no script tag changes are needed. (Script-tag attributes like `data-replay-batch-size` and the `data-replay-mask-*` options only tune replay behavior; the on/off switch lives in site settings.)

## What You'll See [#what-youll-see]

* Mouse movements and clicks
* Scrolling behavior
* Page navigation
* Form interactions (with PII masked)
* User details: country, device, browser

## Using Session Replay [#using-session-replay]

* **UX optimization** - Identify where users get stuck or confused
* **Debug issues** - See exactly what happened when users report problems
* **Understand behavior** - Go beyond metrics to see the full user story
* **Share with your team** - Collaborate on findings

## Privacy [#privacy]

Session replay automatically masks sensitive information. Enable PII protection in your settings for additional masking of form inputs and text content.


# Sessions (/docs/feature-guides/sessions)



The Sessions tab shows individual user visits to your website, including all page views, interactions, and events during each session.

## Session Metrics [#session-metrics]

Each session displays:

* **Duration** - Time spent on site
* **Pages Visited** - Number of pages viewed
* **Events Triggered** - Custom events fired during the session
* **Device & Browser** - Technical environment
* **Location** - Geographic location based on IP
* **Entry/Exit Page** - Where the session started and ended
* **Bounce Status** - Whether the user left after one page

## Filtering Sessions [#filtering-sessions]

Filter by:

* Duration, pages visited, or events triggered
* Device type, browser, or location
* Referrer or traffic source
* Date range

## Session Replay [#session-replay]

If [session replay](/docs/product-analytics/replay-session) is enabled, you can watch a recording of any session to see exactly what the user did.


# Users (/docs/feature-guides/users)



The Users tab shows unique visitors and their behavior across multiple sessions.

## User Metrics [#user-metrics]

For each user, you'll see:

* **User ID** - Anonymized identifier
* **First/Last Visit** - When they first and most recently visited
* **Total Sessions** - Number of separate visits
* **Pages Viewed** - Total pages across all sessions
* **Events Triggered** - Total custom events
* **Device Type** - Desktop, mobile, or tablet
* **Location** - Geographic location

## Filtering Users [#filtering-users]

Filter by the standard dimension filters:

* Device type, browser, or operating system
* Country, region, or city
* Referrer, channel, or UTM parameters
* Pages visited (pathname, entry, or exit page)

Session count, pageviews, events, and first/last seen aren't filters, but you can sort the user list by those columns.

## Identified Users [#identified-users]

If you use the [identify API](/docs/identify-users), you can see your own user IDs alongside the anonymous identifiers.


# Claude Code (/docs/mcp/claude-code)



Connecting Claude Code to Rybbit lets it answer analytics questions mid-task — whether the error it just fixed still occurs in production, which pages get traffic before a refactor, whether a newly instrumented event is firing — and wire up goals and funnels as you ship features.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

The simplest way to connect — no API key to create or store:

```bash
claude mcp add --transport http rybbit https://app.rybbit.io/api/mcp
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Then run `/mcp` inside a Claude Code session, select **rybbit**, and choose **Authenticate**. Your browser opens to log in to Rybbit and approve access, and the connection acts with your user's role.

By default the server registers at the `local` scope — available to you in the current project only. Add `--scope user` to use it in all of your projects.

## Team setup [#team-setup]

OAuth makes the team setup trivial: commit a project-scoped `.mcp.json` at the repository root containing only the URL, and each developer authenticates once with `/mcp`. No secret ever touches the repo:

```json
{
  "mcpServers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp"
    }
  }
}
```

## Connect with an API key [#connect-with-an-api-key]

Use an [API key](/docs/mcp#1-create-an-api-key) instead when there is no browser to authenticate in (CI, headless `claude -p` runs) or when you want to hand the agent a narrower, scoped credential:

```bash
claude mcp add --transport http rybbit https://app.rybbit.io/api/mcp \
  --header "Authorization: Bearer <RYBBIT_API_KEY>"
```

In a committed `.mcp.json`, pass the key through an environment variable rather than hard-coding it — Claude Code expands `${VAR}` references from each developer's environment:

```json
{
  "mcpServers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${RYBBIT_API_KEY}"
      }
    }
  }
}
```

## Verify [#verify]

Run `claude mcp list` (or `/mcp` inside a session) to confirm the server shows as connected, then try:

> List my Rybbit sites and summarize last week's traffic for each.


# Claude Desktop (/docs/mcp/claude-desktop)





Adding Rybbit as a custom connector turns Claude into a conversational analytics interface: ask how a launch went, why traffic spiked on Tuesday, or where a funnel drops off — without opening the dashboard. Connectors are shared across claude.ai, Claude Desktop, and the mobile apps.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, the full tool list, permissions, and troubleshooting.

## Add the connector [#add-the-connector]

1. Open **Settings → Connectors** (in Claude Desktop: `Cmd/Ctrl + ,`, then **Connectors**; on claude.ai: your profile menu → **Settings** → **Connectors**).

2. Click **Add custom connector**.

3. Name it **Rybbit** and paste the endpoint URL:

   ```text
   https://app.rybbit.io/api/mcp
   ```

   For a self-hosted installation, use your configured `BASE_URL` host instead.

4. Confirm, then click **Connect**. Your browser opens Rybbit's [OAuth flow](/docs/mcp#or-connect-with-oauth) — log in and approve access. The connector acts with your user's role.

There is no API key to manage: custom connectors authenticate through OAuth, and the **Advanced settings** fields (OAuth client ID and secret) can stay empty — Rybbit registers the client automatically. Custom connectors are available on all Claude plans; the Free plan is limited to one.

<Callout type="warn">
  **Self-hosted installations must be publicly reachable.** Claude connects to
  custom connectors from Anthropic's infrastructure, not from your device — a
  Rybbit instance on a private network, behind a VPN, or on `localhost` will
  not connect, even if you can reach it in your own browser.
</Callout>

## Use it [#use-it]

Once connected, Rybbit appears in the chat's tools menu — enable it there if it isn't already. Then try:

> List my Rybbit sites and summarize last month's traffic for the main one.

Claude asks for confirmation before tool calls by default; destructive tools (deleting goals, funnels, sites) are marked so it always confirms those.


# Codex (/docs/mcp/codex)



Connecting Codex to Rybbit lets it check analytics as part of your development workflow — verifying that a fixed error stopped occurring, checking which routes get traffic before a refactor, or creating goals and funnels for features as you ship them.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

The simplest way to connect — add the server and log in:

```bash
codex mcp add rybbit --url https://app.rybbit.io/api/mcp
codex mcp login rybbit
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

`codex mcp login` opens your browser to log in to Rybbit and approve access; the connection acts with your user's role.

## Connect with an API key [#connect-with-an-api-key]

Use an [API key](/docs/mcp#1-create-an-api-key) instead for non-interactive runs or a narrower, scoped credential. Register the name of an environment variable holding the key:

```bash
codex mcp add rybbit --url https://app.rybbit.io/api/mcp \
  --bearer-token-env-var RYBBIT_API_KEY
```

Codex reads the key from that variable rather than storing it, so `RYBBIT_API_KEY` must be exported in the shell that launches Codex. Equivalently, configure it in `~/.codex/config.toml`:

```toml
[mcp_servers.rybbit]
url = "https://app.rybbit.io/api/mcp"
bearer_token_env_var = "RYBBIT_API_KEY"
```

## Verify [#verify]

Run `codex mcp list` (or `/mcp` inside the Codex TUI) to confirm the server is connected, then try:

> List my Rybbit sites and summarize last week's traffic for each.


# Cursor (/docs/mcp/cursor)



Connecting Cursor to Rybbit lets its agent check analytics while you code — confirming an error fix landed in production, checking traffic to a route before deleting it, or setting up goals and funnels for a new feature.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Add the server [#add-the-server]

1. [Create an API key](/docs/mcp#1-create-an-api-key) in Rybbit.
2. Add the server to `~/.cursor/mcp.json` (global — available in all projects) or `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "rybbit": {
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer <RYBBIT_API_KEY>"
      }
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Prefer the global file for a personal key. If you configure the server in a project's `.cursor/mcp.json`, don't commit the key — give each developer their own, ideally [scoped](/docs/mcp#1-create-an-api-key) to what the agent needs.

## Verify [#verify]

Open **Cursor Settings → MCP**: the server should show as connected with its tool list, and can be toggled on and off there. Then ask the agent:

> List my Rybbit sites and summarize last week's traffic for each.


# MCP (/docs/mcp)





Rybbit includes a hosted [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) endpoint. It gives an AI assistant read and write access to your analytics: exploring traffic and behavior data, and managing sites, goals, funnels, organization members, teams, and user profiles — through the same API the dashboard uses, with the same access checks, roles, and rate limits.

Your MCP client connects to Rybbit over HTTPS and sends your API key with each protocol request. Rybbit verifies the key before processing any message, and every tool call is authorized against the key user's role and site access.

## Connect a client [#connect-a-client]

If your client supports the MCP authorization flow — Claude Code, Codex, Claude Desktop, and opencode all do — you can [connect with OAuth](#or-connect-with-oauth) and skip API keys entirely. The steps below describe the API-key path, which works in every client and supports scoped credentials.

### 1. Create an API key [#1-create-an-api-key]

1. Open **Settings → Account** in Rybbit.
2. Create a key in the **Personal API Keys** section.
3. Copy it immediately. Rybbit only shows a new key once.

A key created without permissions can do everything its user can do. To hand an agent a narrower credential, create the key with scoped permissions (`POST /api/user/api-keys` with a `permissions` object, e.g. `{"analytics": ["read"], "goals": ["read", "write"]}`): the MCP tool list and every API call are then limited to those `resource:action` scopes. `write` implies `read` on the same resource, and scopes never elevate — org admin/owner requirements still apply. Deleting the key revokes the connection.

### 2. Add the endpoint [#2-add-the-endpoint]

Use this Streamable HTTP URL for Rybbit Cloud:

```text
https://app.rybbit.io/api/mcp
```

For a self-hosted installation, replace the host with your configured `BASE_URL`:

```text
https://analytics.example.com/api/mcp
```

Configure your client to send this header on every request:

```text
Authorization: Bearer <RYBBIT_API_KEY>
```

MCP clients use different configuration formats. A typical remote-server configuration has this shape:

```json
{
  "mcpServers": {
    "rybbit": {
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer <RYBBIT_API_KEY>"
      }
    }
  }
}
```

Use your client's secret or environment-variable support when available instead of saving the key in a file. Query-string API keys are not accepted by the MCP endpoint. Per-client walkthroughs — Claude Code, Codex, Claude Desktop, Cursor, VS Code, opencode — are in [Client guides](#client-guides) below.

### Or connect with OAuth [#or-connect-with-oauth]

Clients that support the MCP authorization flow can skip API keys entirely: add the endpoint URL with no headers, and the client discovers Rybbit's authorization server through the standard well-known metadata (`/.well-known/oauth-protected-resource`), registers itself, and opens a browser window for you to log in and approve access. The resulting access token acts with your user's role, exactly like an API key would.

OAuth grants support the same `resource:action` scopes as API keys (advertised in `scopes_supported`). A grant that requests only the standard OIDC scopes is unrestricted; a grant that requests custom scopes like `analytics:read` is limited to them. The requesting client controls which scopes it asks for — consent is currently approve-or-deny as a whole.

### 3. Start with context [#3-start-with-context]

Ask the assistant to call `list_sites`, or prompt it with something like:

> List my Rybbit sites, summarize last month's traffic for the docs site, and create a goal for signups.

`list_sites` returns the numeric `site_id` and `organization_id` required by the other tools, plus the key's role in each organization. It does not return API keys or member email addresses.

## Client guides [#client-guides]

Coding agents can use the endpoint to pull analytics into your development workflow — checking whether an error you just fixed still occurs in production, or looking up which pages matter before a refactor — and chat clients like Claude Desktop turn it into a conversational analytics interface. Follow the guide for your client:

<Cards>
  <Card icon="<SiClaude />" title="Claude Code" description="One command with OAuth or an API key, plus a no-secrets team setup" href="/docs/mcp/claude-code" />

  <Card title="Codex" description="codex mcp add, then OAuth login or a key from the environment" href="/docs/mcp/codex" />

  <Card icon="<SiClaude />" title="Claude Desktop" description="Add a custom connector on claude.ai, desktop, and mobile" href="/docs/mcp/claude-desktop" />

  <Card title="Cursor" description="mcp.json with an API key header" href="/docs/mcp/cursor" />

  <Card title="VS Code" description="Copilot agent mode, with the key kept out of the config file" href="/docs/mcp/vscode" />

  <Card title="opencode" description="Remote server config with OAuth login or env-based headers" href="/docs/mcp/opencode" />
</Cards>

Any other MCP client that supports Streamable HTTP works with the generic configuration from [step 2](#2-add-the-endpoint).

## Available tools [#available-tools]

### Analytics (read) [#analytics-read]

| Tool                      | Returns                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `get_overview`            | Sessions, pageviews, users, pages per session, bounce rate, and session duration       |
| `get_overview_timeseries` | The overview KPIs bucketed over time                                                   |
| `get_breakdown`           | Sessions broken down by one dimension (pages, referrers, countries, devices, UTM, ...) |
| `get_live_stats`          | Visitors active on the site right now                                                  |
| `get_event_names`         | Custom event names tracked on the site with counts                                     |
| `get_errors`              | JavaScript errors grouped by name/message with occurrence counts                       |
| `get_web_vitals`          | Core Web Vitals percentiles (LCP, CLS, INP, FCP, TTFB)                                 |
| `get_retention`           | User retention cohort table                                                            |
| `get_journeys`            | Most common page-to-page navigation paths                                              |
| `get_annotations`         | Notes pinned to dates on the traffic chart (launches, deploys, campaigns, outages)     |
| `list_segments`           | Saved segments: named, reusable filter sets for a site or the whole organization       |
| `apply_segment`           | Overview KPIs for visitors matching a saved segment, with its filters for reuse        |

### Sites [#sites]

| Tool                 | Does                                                                                   |
| -------------------- | -------------------------------------------------------------------------------------- |
| `list_sites`         | List organizations and sites the key can access (call this first)                      |
| `get_site`           | One site's full configuration                                                          |
| `create_site`        | Add a new site to an organization &#x2A;(admin)*                                       |
| `update_site_config` | Change site settings: name, domain, tracking features, exclusions, tags &#x2A;(admin)* |
| `delete_site`        | Permanently delete a site and its data &#x2A;(admin, destructive)*                     |

### Goals & funnels [#goals--funnels]

| Tool             | Does                                                   |
| ---------------- | ------------------------------------------------------ |
| `get_goals`      | Conversion goals with conversion stats                 |
| `create_goal`    | Create a path, event, or autocapture goal              |
| `update_goal`    | Replace a goal's definition                            |
| `delete_goal`    | Permanently delete a goal &#x2A;(destructive)*         |
| `get_funnels`    | Saved funnel definitions                               |
| `analyze_funnel` | Compute an ad-hoc funnel without saving it             |
| `save_funnel`    | Save a funnel, or update one by passing `funnel_id`    |
| `delete_funnel`  | Permanently delete a saved funnel &#x2A;(destructive)* |

### People [#people]

| Tool                 | Does                                                                        |
| -------------------- | --------------------------------------------------------------------------- |
| `get_users`          | Person inventory with per-user aggregates and traits (sortable, searchable) |
| `get_user`           | One person's profile: traits, linked devices, vitals, locations             |
| `identify_user`      | Link an anonymous device to your user ID and merge traits                   |
| `update_user_traits` | Replace a person's traits wholesale                                         |
| `delete_user`        | GDPR erasure of one person's analytics data &#x2A;(admin, destructive)*     |

### Organization & teams [#organization--teams]

| Tool                        | Does                                                           |
| --------------------------- | -------------------------------------------------------------- |
| `list_members`              | Organization members with roles, site access, and teams        |
| `add_member`                | Add an existing Rybbit user to the organization &#x2A;(admin)* |
| `update_member_site_access` | Restrict a member to specific sites &#x2A;(admin)*             |
| `list_teams`                | Teams with members and site access                             |
| `create_team`               | Create a team &#x2A;(admin)*                                   |
| `update_team`               | Rename a team or replace its members/sites &#x2A;(admin)*      |
| `delete_team`               | Permanently delete a team &#x2A;(admin, destructive)*          |

### Raw data & SQL [#raw-data--sql]

| Tool               | Does                                                                   |
| ------------------ | ---------------------------------------------------------------------- |
| `get_sessions`     | Recent visitor sessions with full attribution                          |
| `get_session`      | One session's detail plus its event timeline                           |
| `get_events`       | Raw recent events, newest first                                        |
| `get_query_schema` | The ClickHouse schema and rules for `run_query`                        |
| `run_query`        | Read-only ClickHouse SQL against the site-scoped `scoped_events` table |

Analytics tools accept optional time inputs (`start_date`/`end_date` with an IANA `time_zone`, or `past_minutes`) and the same filters as the dashboard. Omitting time inputs queries all time; an unrecognized `time_zone` is rejected before the call is made. `get_sessions`, `get_events`, and `get_users` accept an optional `fields` list to return only the named row columns, which keeps large result sets small.

## Permissions and roles [#permissions-and-roles]

The MCP surface mirrors the REST API's permission model:

* **Read tools** work for any member with access to the site.
* **Write tools** need at least member-level site access (goals, funnels, `identify_user`, `update_user_traits`, `save_funnel`).
* **Tools marked &#x2A;(admin)*** require the API key's user to hold the **admin or owner** role in the organization; `add_member` can grant the `owner` role only from an owner's key. The REST layer enforces all of this — an underprivileged key gets a 403 with an explanatory message.

To give an assistant a read-only or read-mostly view, create a **scoped** API key (see step 1): grant only the `resource:action` scopes it needs — e.g. `{"analytics": ["read"], "sessions": ["read"]}` for a reporting agent. The MCP tool list is filtered to those scopes, and any out-of-scope call returns `403 { "error": "Insufficient scope", "required": "goals:write" }`. Alternatively, connecting with a member-role user's key hides nothing but refuses every call requiring the admin/owner role.

OAuth clients request scopes through the standard grant. Rybbit advertises the same `resource:action` scopes in its discovery metadata; a grant carrying no custom scopes (or only the standard OIDC scopes) is treated as full access, for backward compatibility.

## Destructive tools [#destructive-tools]

`delete_goal`, `delete_funnel`, `delete_site`, `delete_team`, and `delete_user` permanently destroy data and are marked with the MCP `destructiveHint` annotation, so well-behaved clients ask for confirmation before invoking them. `delete_site` and `delete_user` (the GDPR-erasure path) also remove recorded events and replays, with erasure completing asynchronously.

## Data and security boundary [#data-and-security-boundary]

* The API key is verified before any MCP message is processed, and each tool call re-runs the corresponding REST route's own access checks, role requirements, and rate limits.
* The surface returns whatever the REST API returns for your role — including session-level records and, where a site has IP tracking enabled, visitor IP addresses. Connect only AI clients you trust with that data, and use a separate, revocable API key per integration.
* Text originating in tracked traffic (page titles, paths, referrers, event names, traits) is stripped of control and bidi-override characters. AI clients should still treat these values as untrusted data, never as instructions.
* `run_query` is restricted to a read-only, site-scoped table with row and execution-time caps.
* The server does not contain an AI model or send analytics to an AI provider. Data only leaves Rybbit in response to the MCP client you configure.
* The endpoint is stateless. Each HTTP request is independently authenticated.

## Troubleshooting [#troubleshooting]

* **401 Unauthorized:** The client did not send a Bearer credential, or the key/token is invalid, expired, or revoked. OAuth-capable clients re-authenticate automatically via the `WWW-Authenticate` challenge.
* **OAuth login loop or "table does not exist" (self-hosted):** Run `npm run db:push` in `server/` to create the OAuth tables, then retry.
* **403 in tool results:** The key's user lacks access to that site or organization — or the tool requires an org admin/owner role. Check the `role` field in `list_sites`.
* **403 "Insufficient scope":** The credential was created without the `resource:action` scope this tool needs (the `required` field names it). Use a key or OAuth grant that includes it.
* **429 Too Many Requests:** The API key exceeded its plan's rate limit.
* **503 Service Unavailable:** Rybbit could not verify the key. Retry the request; do not replace a known-valid key based on this response.
* **405 Method Not Allowed on GET:** This is expected. The stateless endpoint accepts MCP messages over `POST`.
* **Site access error:** Call `list_sites` again. Membership or site permissions may have changed.


# opencode (/docs/mcp/opencode)



Connecting opencode to Rybbit lets it pull analytics into your terminal workflow — verifying an error fix in production, checking a route's traffic before removing it, or wiring up goals and funnels as you ship.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

Add the server to `opencode.json` at your project root (or your global opencode config):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rybbit": {
      "type": "remote",
      "url": "https://app.rybbit.io/api/mcp",
      "enabled": true
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Then authenticate:

```bash
opencode mcp auth rybbit
```

Your browser opens Rybbit's [OAuth flow](/docs/mcp#or-connect-with-oauth) — log in and approve access. The connection acts with your user's role, and the committed config carries no secret. `opencode mcp logout rybbit` removes the stored credential.

## Connect with an API key [#connect-with-an-api-key]

To use an [API key](/docs/mcp#1-create-an-api-key) instead — for non-interactive runs or a narrower, scoped credential — add a headers block that reads the key from the environment, so the config stays committable:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rybbit": {
      "type": "remote",
      "url": "https://app.rybbit.io/api/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:RYBBIT_API_KEY}"
      }
    }
  }
}
```

## Verify [#verify]

Run `opencode mcp list` to see the server and its authentication status (`opencode mcp debug rybbit` gives detailed diagnostics), then try:

> List my Rybbit sites and summarize last week's traffic for each.


# VS Code (/docs/mcp/vscode)



Connecting VS Code to Rybbit gives Copilot's agent mode access to your analytics — checking whether a fixed error still occurs, looking up which pages matter before a refactor, or creating goals for a feature as you build it.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Add the server [#add-the-server]

1. [Create an API key](/docs/mcp#1-create-an-api-key) in Rybbit.
2. Create `.vscode/mcp.json` in your workspace. The `inputs` block keeps the key out of the file — VS Code prompts for it once when the server first starts and stores it securely, so this file is safe to commit:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "rybbit-api-key",
      "description": "Rybbit API key",
      "password": true
    }
  ],
  "servers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:rybbit-api-key}"
      }
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

To make the server available in every workspace instead, run **MCP: Open User Configuration** from the Command Palette and add the same JSON there. **MCP: Add Server** offers a guided setup as an alternative to editing the file.

## Verify [#verify]

Run **MCP: List Servers** from the Command Palette — Rybbit should be listed with its tools, which also appear in the tools picker in Copilot's agent mode. Then ask the agent:

> List my Rybbit sites and summarize last week's traffic for each.


# Angular (/docs/guides/angular)





An Angular CLI project serves one HTML shell, `src/index.html`, for every route. Paste the snippet into its `<head>` and the script loads once for the whole app.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Angular [#add-the-snippet-to-angular]

    Open `src/index.html` and paste the snippet just before `</head>`:

    ```html title="src/index.html"
    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>MyAngularApp</title>
      <base href="/">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
      <app-root></app-root>
    </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Navigation through the Angular Router is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Declare `rybbit` on `window` once so TypeScript accepts the call, then call `window.rybbit.event()` from any component or service. Guard the call so a blocked script does not throw.

```typescript title="src/app/feature/feature.component.ts"
import { Component } from "@angular/core";

declare global {
  interface Window {
    rybbit?: {
      event: (eventName: string, eventData?: Record<string, any>) => void;
      pageview: () => void;
    };
  }
}

@Component({
  selector: "app-feature",
  template: `<button (click)="onFeatureClick()">Use Feature</button>`,
})
export class FeatureComponent {
  onFeatureClick(): void {
    if (window.rybbit) {
      window.rybbit.event("feature_used", { featureName: "Amazing Feature" });
    }
  }
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: this is rare. If it happens, subscribe to `Router.events`, filter for `NavigationEnd` and call `window.rybbit.pageview()`; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ASP.NET Core (/docs/guides/aspnet)





ASP.NET Core MVC and Razor Pages apps share one layout file, `_Layout.cshtml`, that wraps every view, so the snippet goes into its `<head>`. Keep the site ID in `appsettings.json` and inject `IConfiguration` into the layout so nothing is hard-coded.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ASP.NET Core [#add-the-snippet-to-aspnet-core]

    #### Configure the site ID [#configure-the-site-id]

    Add a `Rybbit` section to `appsettings.json`:

    ```json filename="appsettings.json"
    {
      "Rybbit": {
        "InstanceUrl": "https://app.rybbit.io",
        "SiteId": "YOUR_SITE_ID"
      }
    }
    ```

    To keep the ID out of source control or vary it per environment, leave `SiteId` empty in `appsettings.json` and set it in `appsettings.Production.json`, or as the environment variable `Rybbit__SiteId` (double underscore separates configuration sections).

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open the layout file:

    * Controllers with views: `Views/Shared/_Layout.cshtml`
    * Razor Pages: `Pages/Shared/_Layout.cshtml`

    Inject `IConfiguration` at the top and add the tag inside `<head>`:

    ```razor filename="Views/Shared/_Layout.cshtml"
    @inject IConfiguration Configuration
    @{
        var rybbitSiteId = Configuration["Rybbit:SiteId"];
        var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
    }
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>@ViewData["Title"] - MyApp</title>
        <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />

        @if (!string.IsNullOrEmpty(rybbitSiteId))
        {
            <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
        }
    </head>
    ```

    If `Microsoft.Extensions.Configuration` is not already imported in `_ViewImports.cshtml`, add `@using Microsoft.Extensions.Configuration` above the `@inject` line.

    The `@if` guard skips the tag when `SiteId` is empty, so development is not tracked unless you set the value there. If your app has more than one layout, add the tag to each, or move it into a partial view and render it with `<partial name="_Rybbit" />` from every layout.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: environment-specific files such as `appsettings.Development.json` override `appsettings.json`, so check which environment you are running (`ASPNETCORE_ENVIRONMENT`) and that the `Rybbit` section exists there or in the base file. Environment variables override both.
* **Content Security Policy**: if middleware adds a `Content-Security-Policy` header, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Response caching or output caching**: the tag is rendered server-side, so a cached response keeps whatever configuration was active when it was cached. Clear the cache after changing the site ID.
* **Self-hosted instance**: set `Rybbit:InstanceUrl` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Astro (/docs/guides/astro)





Astro pages share a layout component that renders the `<html>` document. Add the snippet to the `<head>` of that layout and every page that uses it is tracked.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Astro [#add-the-snippet-to-astro]

    Open your shared layout, usually `src/layouts/Layout.astro`, and paste the snippet inside `<head>`. Add `is:inline` so Astro leaves the tag as-is instead of bundling it:

    ```astro title="src/layouts/Layout.astro"
    ---
    const { title } = Astro.props;
    ---
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title>{title}</title>
        <script is:inline src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <slot />
      </body>
    </html>
    ```

    If you do not use a shared layout, add the same tag to the `<head>` of each page in `src/pages/`. A layout is easier to maintain.

    Astro builds a multi-page site by default, so each navigation is a full page load and a new pageview. With [view transitions](https://docs.astro.build/en/guides/view-transitions/) enabled, client-side navigation is tracked automatically when the URL changes.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a client-side `<script>` in any `.astro` component, or from inside a framework island the same way you would in that framework.

```astro title="src/components/TrackedButton.astro"
<button id="tracked-button">Click me</button>

<script>
  document.getElementById("tracked-button")?.addEventListener("click", () => {
    if (window.rybbit) {
      window.rybbit.event("astro_button_click", { source: "TrackedButton.astro" });
    }
  });
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing with view transitions**: this is rare. If it happens, listen for Astro's `astro:after-swap` event in a client-side script and call `window.rybbit.pageview()`; test the default behaviour first.
* **Proxying through your own domain**: Astro can serve the script from your domain with SSR middleware. See the [Astro proxy guide](/docs/proxy-guide/astro).

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# BigCommerce (/docs/guides/bigcommerce)





BigCommerce's **Script Manager** adds scripts to every storefront page without theme edits, and it is also where the order-confirmation purchase event goes. Editing the theme's `head.html` works too.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to BigCommerce [#add-the-snippet-to-bigcommerce]

    <Tabs items="[&#x22;Script Manager&#x22;, &#x22;Theme files&#x22;]">
      <Tab>
        1. In the control panel, go to **Storefront > Script Manager** and click **Create a Script**.
        2. Fill in the settings:
           * **Name**: Rybbit Analytics
           * **Placement**: Head
           * **Location**: All pages
           * **Script category**: Analytics
           * **Script type**: Script
        3. Paste the snippet into **Script contents** and click **Save**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Back up your theme before editing files.
        </Callout>

        1. Go to **Storefront > Themes**, click **Advanced** on your current theme, then **Edit Theme Files**.
        2. Open **templates > components > common** and then `head.html`.
        3. Paste the snippet at the end of the file, before the closing `</head>` tag, and click **Save**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Create a second script in Script Manager with **Placement: Footer**, **Location: Order Confirmation** and **Script type: Script**. BigCommerce runs Script Manager contents through Handlebars, so expressions such as `checkout.order.id` are filled in with the order data before the page is served:

```html
<script>
(function () {
  function waitForRybbit(callback, timeout) {
    var start = Date.now();
    (function check() {
      if (window.rybbit && typeof window.rybbit.event === 'function') {
        callback();
      } else if (Date.now() - start < timeout) {
        setTimeout(check, 100);
      }
    })();
  }

  waitForRybbit(function () {
    {{#if checkout.order}}
    window.rybbit.event('purchase', {
      transaction_id: '{{checkout.order.id}}',
      value: {{checkout.subtotal.value}},
      currency: '{{checkout.currency.code}}'
    });
    {{/if}}
  }, 5000);
})();
</script>
```

`waitForRybbit` polls until the tracking script from the head has defined `window.rybbit`, so the event is not lost if the confirmation page runs the footer script first.

## Troubleshooting [#troubleshooting]

* **Script not on the page**: confirm the script is enabled in Script Manager, then purge the store cache under **Server Settings > Store-level caching > Purge cache**.
* **Purchase event missing**: the purchase script must use the **Order Confirmation** location, and the `checkout.order`, `checkout.subtotal` and `checkout.currency` Handlebars objects depend on your BigCommerce checkout version. Place a test order to confirm the event arrives.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Blazor (/docs/guides/blazor)





Where the snippet goes depends on the Blazor hosting model: a Blazor Web App keeps its `<head>` in `Components/App.razor`, a standalone Blazor WebAssembly app in `wwwroot/index.html`, and a Blazor Server app (.NET 7 and earlier) in `Pages/_Host.cshtml`. In each case the tag is added once and stays on the page while Blazor handles navigation client-side.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Blazor [#add-the-snippet-to-blazor]

    <Tabs items="[&#x22;Blazor Web App&#x22;, &#x22;Blazor WebAssembly (standalone)&#x22;, &#x22;Blazor Server (.NET 7 and earlier)&#x22;]">
      <Tab>
        `App.razor` is rendered on the server, so it can read the site ID from `appsettings.json`. Add a `Rybbit` section:

        ```json filename="appsettings.json"
        {
          "Rybbit": {
            "InstanceUrl": "https://app.rybbit.io",
            "SiteId": "YOUR_SITE_ID"
          }
        }
        ```

        Then inject `IConfiguration` in `Components/App.razor` and add the tag inside `<head>`:

        ```razor filename="Components/App.razor"
        @inject IConfiguration Configuration
        @{
            var rybbitSiteId = Configuration["Rybbit:SiteId"];
            var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
        }
        <!DOCTYPE html>
        <html lang="en">

        <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <base href="/" />
            <link rel="stylesheet" href="@Assets["app.css"]" />
            <HeadOutlet />

            @if (!string.IsNullOrEmpty(rybbitSiteId))
            {
                <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
            }
        </head>
        ```

        Override the value per environment with `appsettings.Production.json` or the environment variable `Rybbit__SiteId`.
      </Tab>

      <Tab>
        A standalone WebAssembly app ships `wwwroot/index.html` as a static file, so add the tag directly inside `<head>`:

        ```html filename="wwwroot/index.html"
        <head>
            <base href="/" />
            <link rel="stylesheet" href="css/app.css" />

            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        The site ID is public on every platform (it is in the page source), so a static value here is fine; `wwwroot/appsettings.json` is equally visible to the browser and offers no advantage for this value.
      </Tab>

      <Tab>
        Add the `Rybbit` section to `appsettings.json` as in the Blazor Web App tab, then open `Pages/_Host.cshtml` (or `Pages/_Layout.cshtml` in .NET 6 projects, where the `<head>` lives) and add the tag:

        ```razor filename="Pages/_Host.cshtml"
        @page "/"
        @using Microsoft.Extensions.Configuration
        @inject IConfiguration Configuration
        @{
            var rybbitSiteId = Configuration["Rybbit:SiteId"];
            var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
        }
        <!DOCTYPE html>
        <html lang="en">
        <head>
            <base href="~/" />
            <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

            @if (!string.IsNullOrEmpty(rybbitSiteId))
            {
                <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
            }
        </head>
        ```
      </Tab>
    </Tabs>

    #### Navigation [#navigation]

    Blazor's router, `NavigationManager.NavigateTo` and enhanced navigation in Blazor Web Apps all update the URL through `history.pushState` (or `replaceState` when `replace: true`) rather than reloading the page. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). Enhanced navigation patches the DOM without re-running scripts already in `<head>`, which is what you want: the tracker loads once and keeps running. `NavigateTo(url, forceLoad: true)` and links with `data-enhance-nav="false"` do a full page load, which the script tracks as a new pageview.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in a Blazor Web App**: `App.razor` reads server-side configuration, so check the `appsettings` file for the active `ASPNETCORE_ENVIRONMENT`; environment variables override the files.
* **Blazor WebAssembly PWA**: `index.html` is cached by the service worker. Users receive the new tag only after the app is republished and the service worker updates.
* **Content Security Policy**: if you set one, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `Rybbit:InstanceUrl` (or the static URL in `index.html`) to your own domain without a trailing slash.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Bolt (/docs/guides/bolt)





Bolt has no settings field for custom head code (its **Analytics** project setting only shows traffic for published sites), so the snippet goes into the app's HTML head as a code change: prompt Bolt to add it, or switch to Code view and paste it into the root HTML or layout file. Publish the project again afterwards.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Bolt [#add-the-snippet-to-bolt]

    <Tabs items="[&#x22;Ask Bolt&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of every page and keep all existing head tags:
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Review the change Bolt makes before you move on: the tag should be in the document head, not inside a component.
      </Tab>

      <Tab>
        Click the **Code Preview** icon (`<>`) at the top center to switch to Code view, then open the file that owns the `<head>` for the framework Bolt chose:

        * **Vite** projects (React, Vue, Svelte): `index.html` at the project root.
        * **Next.js** projects: `app/layout.tsx`, using the `next/script` component as in the [Next.js guide](/docs/guides/react/next-js).
        * Any other framework: ask Bolt "which file renders the HTML head?" and edit that one.

        For a Vite project, paste the snippet before `</head>`:

        ```html title="index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Click **Save** or press **Ctrl+S**.
      </Tab>
    </Tabs>

    Publish the change: open the **Publish** menu and click **Publish** the first time, or **Update** for a site that is already live. In-app navigation is tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Published site unchanged**: edits are not applied to the live site until you click **Update** in the **Publish** menu.
* **Bolt removed the tag**: later prompts can regenerate `index.html` or the layout. Right-click the file in the **Files** list and choose **Lock file** so Bolt leaves it alone, or add a line to the project's **Knowledge** telling it to keep the Rybbit script.
* **Expo (mobile) projects**: a script tag only runs in the web build. For the native app, use the [JavaScript SDK](/docs/sdks/web) instead.
* **Numbers differ from Bolt's Analytics**: Bolt's built-in counts include crawlers and bots; Rybbit filters them.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Bubble.io (/docs/guides/bubble)





Bubble adds custom header code to every page of your app through the **SEO / metatags** settings tab, so the snippet goes there once and ships with your next deploy.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Bubble.io [#add-the-snippet-to-bubbleio]

    1. Open your app in the Bubble editor and click the **Settings** tab in the left sidebar.
    2. Open the **SEO / metatags** sub-tab.
    3. Scroll to **Script/meta tags in header** and paste the snippet. It is added to the `<head>` of every page in the app.
    4. Deploy the app to **Live**. The development version does not pick up the change until you deploy.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Bubble workflows can run arbitrary JavaScript through a **Run JavaScript** action (provided by the free Toolbox plugin). Use it to send events from any workflow trigger.

1. Open the **Workflow** tab and pick the trigger, for example *When Button Signup is clicked*.
2. Add a **Run JavaScript** action.
3. Paste the call, using Bubble's dynamic expressions for the values:

```javascript
if (window.rybbit) {
  window.rybbit.event("signup_clicked", {
    plan: "Current User's Plan",
  });
}
```

## Troubleshooting [#troubleshooting]

* **Only the first pageview is tracked**: Bubble apps that switch between groups on a single page do not change the URL, so there is nothing for the script to detect. Add a **Run JavaScript** action that calls `window.rybbit.pageview()` when the group becomes visible, or track those views as custom events. Apps that navigate between real Bubble pages are tracked automatically.
* **Snippet missing on the live site**: the header script is versioned with your app, so check that you deployed to Live after saving the setting.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Capacitor (/docs/guides/capacitor)





Capacitor wraps a normal web app in a native WebView, so the snippet goes in the `<head>` of that web app's `index.html` and ships to iOS and Android with `npx cap sync`. If the app is built with Ionic Angular, React or Vue, follow the [Angular](/docs/guides/angular), [React](/docs/guides/react/vite-cra) or [Vue](/docs/guides/vue/vite) guide for where the tag lives, then come back here for the WebView origin settings.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Capacitor [#add-the-snippet-to-capacitor]

    1. Paste the snippet into the `<head>` of your web app's `index.html` (the file in the `webDir` folder from `capacitor.config`, after your framework's build):

    ```html title="index.html"
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    2. Enable `CapacitorHttp`, which routes `window.fetch` through native HTTP. The iOS WebView runs on `capacitor://localhost`, and Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so without this the browser blocks the requests on iOS:

    ```ts title="capacitor.config.ts"
    import type { CapacitorConfig } from "@capacitor/cli";

    const config: CapacitorConfig = {
      appId: "com.example.app",
      appName: "My App",
      webDir: "dist",
      plugins: {
        CapacitorHttp: {
          enabled: true,
        },
      },
    };

    export default config;
    ```

    3. Build the web app, then copy it into the native projects:

    ```bash
    npm run build
    npx cap sync
    ```

    Android serves the app from `https://localhost` (`server.androidScheme` defaults to `https`), which is a regular origin, so tracking works there with or without `CapacitorHttp`. In-app route changes are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.

    <Callout type="info">
      Use the script tag rather than the `@rybbit/js` npm package on Capacitor. The package sends events with `navigator.sendBeacon`, which `CapacitorHttp` does not patch, so its requests from `capacitor://localhost` are still blocked on iOS.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Works on Android and in the browser, silent on iOS**: `CapacitorHttp` is not enabled, or the native projects were not re-synced after changing the config. Run `npx cap sync` and rebuild in Xcode.
* **Changes do not appear on device**: `npx cap sync` copies the built web bundle; edit the source, rebuild the web app, then sync again.
* **Live reload during development**: with `server.url` pointing at your dev server the WebView loads an `http://` origin, so requests succeed even without `CapacitorHttp`. Do not read a working dev build as proof that the production build is configured.
* **Every pageview shows `localhost` as hostname**: expected. `server.hostname` defaults to `localhost` on both platforms; filter by site, not hostname.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Carrd (/docs/guides/carrd)





Carrd builds one-page sites, and the snippet goes into the **Head** embed code field in the site settings.

<Callout type="warn">
  Custom head code requires a **Carrd Pro** subscription (Pro Standard or Pro Plus). The Embed Code feature is not included on Pro Lite.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Carrd [#add-the-snippet-to-carrd]

    1. Open your site in the Carrd editor and click the **Settings** gear in the top right.
    2. Open the **Settings** tab and scroll to **Embed Code**.
    3. Paste the following into the **Head** field:

    ```html
    <script>
      (function () {
        var s = document.createElement("script");
        s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
        s.defer = true;
        document.head.appendChild(s);
      })();
    </script>
    ```

    This wraps the snippet in a small loader so Carrd's embed processing cannot rewrite the tag.

    4. Click **Save**, then **Publish**. Changes are not live until you publish.

    If your site has multiple pages (a Pro Plus feature), the head code loads on all of them.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **The Head field is missing**: the site is on Pro Lite or the free plan. Upgrade to Pro Standard or Pro Plus.
* **Snippet not in the page source**: the site was saved but not published. Publish again from the editor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Chrome extension (/docs/guides/chrome-extension)





Manifest V3 requires every piece of executable code to ship inside the extension package, and the `extension_pages` Content Security Policy is fixed at `script-src 'self' 'wasm-unsafe-eval'; object-src 'self'` with no way to relax it. A remote `<script>` tag can therefore never load in an extension page. Bundle the `@rybbit/js` SDK into your popup, options or side panel page instead, and grant `host_permissions` for the analytics host.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.

    You only need the site ID from the snippet; the script tag itself is not used in an extension.
  </Step>

  <Step>
    ### Add the snippet to Chrome extension [#add-the-snippet-to-chrome-extension]

    1. Install the SDK in the extension project:

    ```bash
    npm install @rybbit/js
    ```

    2. Initialise it in the entry script of each extension page you want to track (the popup from `action.default_popup`, the options page from `options_ui.page`, the side panel from `side_panel.default_path`). The SDK needs `window` and `document`, so do not import it in the service worker.

    ```js title="src/popup.js"
    import rybbit from "@rybbit/js";

    await rybbit.init({
      analyticsHost: "https://app.rybbit.io/api",
      siteId: "YOUR_SITE_ID",
    });

    // Extension pages have URLs like chrome-extension://<id>/popup.html.
    // Report a readable path instead:
    rybbit.pageview("/popup");
    ```

    3. Grant the extension permission to call the analytics host. Requests from extension pages to origins listed in `host_permissions` are not subject to CORS:

    ```json title="manifest.json"
    {
      "manifest_version": 3,
      "host_permissions": ["https://app.rybbit.io/*"]
    }
    ```

    4. Build the extension with your bundler (Vite, webpack, Rollup) so `@rybbit/js` ends up inside the package, then reload the unpacked extension at `chrome://extensions`.

    The default extension CSP does not restrict `connect-src`, so no `content_security_policy` entry is required. If you define your own policy, add `https://app.rybbit.io` to its `connect-src`.

    <Callout type="warn">
      Do not initialise the SDK in a content script. Content scripts run inside third-party websites; tracking there records other people's pages under your site ID, and content scripts are subject to the host page's same-origin policy in any case.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `rybbit.event()` from the page script, or use data attributes on buttons in your popup HTML:

```js title="src/popup.js"
document.getElementById("save")?.addEventListener("click", () => {
  rybbit.event("settings_saved", { theme: "dark" });
});
```

```html title="popup.html"
<button data-rybbit-event="upgrade_click" data-rybbit-prop-plan="pro">Upgrade</button>
```

## Troubleshooting [#troubleshooting]

* **`Refused to load the script` in the popup console**: the fixed `extension_pages` CSP blocked a remote tag. Remove it and use the SDK.
* **`POST /api/track` blocked by CORS**: `host_permissions` is missing or does not match. The pattern must include the path wildcard: `https://app.rybbit.io/*`.
* **Self-hosted Rybbit**: replace `https://app.rybbit.io` in both `analyticsHost` and `host_permissions` with your own instance URL.
* **Every pageview shows the extension ID as hostname**: expected. Extension pages live on `chrome-extension://<id>`; use `rybbit.pageview("/name")` for readable paths.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Circle (/docs/guides/circle)





Circle has a **Code snippets** setting that injects custom code into the `<head>` of every page in your community, so the snippet goes there once and covers public pages and logged-in member pages alike.

<Callout type="info">
  Custom CSS/JavaScript snippets are included on all current Circle plans (Professional, Business and Circle Plus).
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Circle [#add-the-snippet-to-circle]

    1. Open your community as an admin and go to **Settings**.
    2. Open **Code snippets**.
    3. Paste the snippet into the **Head code snippets** field.
    4. Click **Save**. Changes apply to the whole community immediately; there is no publish step.

    Circle's own help article for this setting is [Custom code snippets](https://help.circle.so/p/administration/site-management/custom-code-snippets).

    Circle is a single-page app: after the first load, navigating between spaces, posts and courses changes the URL without a full reload. The script tracks these client-side route changes automatically, so each space and post shows up as its own pageview.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Custom domain**: the same head code is served on `yourcommunity.circle.so` and on your custom domain. If both hostnames are in use, keep them under one site in Rybbit so sessions are not split.
* **Post embeds**: custom HTML embedded inside a post is scoped to that post. Put the snippet in head code snippets, not in a post.
* **Nothing tracked while logged in as admin**: Circle applies head code to admins too, so check that your own IP or user is not excluded in Rybbit's site settings before assuming the snippet is missing.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ClickFunnels (/docs/guides/clickfunnels)





ClickFunnels 2.0 has a **Header Code** field at three levels: **Site Settings** for the whole workspace, **Funnel settings** for every page in one funnel, and the page editor for a single page. Add the snippet at the widest level you want tracked and leave the narrower ones empty so it is not loaded twice.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ClickFunnels [#add-the-snippet-to-clickfunnels]

    <Tabs items="[&#x22;Whole site&#x22;, &#x22;One funnel&#x22;, &#x22;One page&#x22;]">
      <Tab>
        1. In your workspace, open the **Site & Blog** app in the left menu and click **Site Settings**.
        2. Paste the snippet into **Header Code**.
        3. Save.

        This applies to every page in the workspace: funnel pages, store pages, courses, blog posts and site pages.
      </Tab>

      <Tab>
        1. Open **Funnels** and click the **Settings** gear next to the funnel (or the **Settings** button in the top-right of the funnel workflow editor).
        2. Paste the snippet into **Head Code**.
        3. Click **Update Funnel**.

        The code loads on every page of that funnel only.
      </Tab>

      <Tab>
        1. Open the page in the page editor.
        2. Go to **Settings > Tracking Code** and paste the snippet into **Header Code**.
        3. Click **Save**.

        The code loads on this page only.
      </Tab>
    </Tabs>

    Save, then open the live page URL to test: header code does not run inside the page editor.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Duplicate pageviews**: the snippet is present at more than one level (site and funnel, or funnel and page). Keep a single copy.
* **Snippet not in the page source**: check which level you pasted it at. Site Settings covers the workspace, funnel settings cover that funnel's pages only, and the page editor covers one page.
* **jQuery**: ClickFunnels pages already include jQuery, so do not load it again in the same header code block; a second copy can break page scripts.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Contentful (/docs/guides/contentful)





Contentful is a headless CMS: it stores content and delivers it over its APIs, but never renders your pages. The tracking snippet therefore goes into the frontend that consumes Contentful, not into Contentful itself.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Contentful [#add-the-snippet-to-contentful]

    <Callout type="info">
      Contentful has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Contentful.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Contentful frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby), which pairs with the official `gatsby-source-contentful` plugin
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Editor previews count as visits**: Contentful's content preview URLs open a preview or draft build of your frontend. Register that deployment as a separate site in Rybbit, or leave the snippet out of preview builds, so editors' previews are not mixed into your production data.
* **The Contentful web app is not tracked**: the snippet only runs on your frontend, so time spent editing in Contentful never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Craft CMS (/docs/guides/craft-cms)





Craft CMS renders pages from Twig templates in the `templates/` folder, so the snippet goes into the base template that your section templates extend. A fresh `craftcms/craft` project ships a single `templates/index.twig` containing the full HTML document; most projects move that boilerplate into a base template and `{% extends %}` it.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Craft CMS [#add-the-snippet-to-craft-cms]

    1. Open the template that owns your `<head>`. In a fresh install that is `templates/index.twig`; in a project with a base template it is the underscore-prefixed file every page extends, such as `templates/_layout.twig`.
    2. Add the tag before `</head>`:

    ```twig title="templates/_layout.twig"
    <!DOCTYPE html>
    <html lang="{{ currentSite.language }}">
    <head>
        <meta charset="utf-8">
        <title>{{ siteName }}</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        {% block content %}{% endblock %}
    </body>
    </html>
    ```

    3. Every section template that extends the base template now loads the script:

    ```twig title="templates/blog/_entry.twig"
    {% extends "_layout" %}

    {% block content %}
        <h1>{{ entry.title }}</h1>
        {{ entry.body }}
    {% endblock %}
    {% endraw %}
    ```

    To keep the site ID out of templates and vary it per environment, read it from `.env` with `{{ getenv('RYBBIT_SITE_ID') }}`, or store it in a Global Set and use `{{ settings.rybbitSiteId }}`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Template caching**: if you wrap the head in `{% cache %}` tags, the change appears only after the cache expires or you run `php craft clear-caches/all`.
* **Live Preview counts as visits**: the control panel's Live Preview renders your template in an iframe with `x-craft-live-preview` in the query string. Wrap the tag in `{% if not craft.app.request.isPreview %}` to leave editors' previews out of your data.
* **Control panel is not tracked**: `/admin` uses Craft's own templates, so the snippet never runs there.
* **Multiple base templates**: if some sections extend a different base (for example `_layout-landing.twig`), add the tag to each one, or move it into a partial and `{% include %}` it from every base.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Discourse (/docs/guides/discourse)





Discourse adds site-wide code through **theme components**. A component has an editable `</head>` section that Discourse injects into every page and, because Discourse ships a strict Content Security Policy, it stamps the required nonce onto script tags placed there. No server access or plugin is needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Discourse [#add-the-snippet-to-discourse]

    1. In the admin sidebar open **Appearance → Themes and components** (older versions: **Admin → Customize → Themes**).
    2. On the **Components** tab click **Install**, choose **Create new**, name it "Rybbit Analytics", make sure the type is **Component** and click **Create**.
    3. Click **Edit CSS/HTML**, stay on the **Common*&#x2A; tab and open the &#x2A;*`</head>`** section (not **Header**, which is the visible page header).
    4. Paste the snippet and click **Save**.
    5. Back on the component page, add your active theme under **Include component on these themes** so the component is enabled.

    Discourse is a single-page app: after the first load, topics and categories open without a full page reload. The tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`, so those navigations are recorded as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Component saved but the script is missing from the page source**: the component is not attached to the active theme. Add the theme under **Include component on these themes**, or add the component from the theme's **Included components** list.
* **Script tag present but blocked**: check the browser console for a CSP error. Scripts added through the `</head>` section receive Discourse's nonce automatically; scripts injected any other way (for example from a plugin's raw HTML) do not.
* **Only the first pageview is recorded**: the **SPA Navigation** setting is off for the site in your Rybbit dashboard. Turn it on under Site Settings.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Django (/docs/guides/django)





Django pages extend a base template, so the snippet goes into the `<head>` of that base template. Put the site ID in `settings.py`, read from an environment variable, and pass it to templates with a small context processor so no template hard-codes the ID.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Django [#add-the-snippet-to-django]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to `settings.py`, reading from the environment:

    ```python filename="settings.py"
    import os

    RYBBIT_INSTANCE_URL = os.environ.get("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
    RYBBIT_SITE_ID = os.environ.get("RYBBIT_SITE_ID", "")
    ```

    Set `RYBBIT_SITE_ID=YOUR_SITE_ID` in your production environment (or your `.env` file if you load one with django-environ or python-dotenv).

    #### Expose the values to templates [#expose-the-values-to-templates]

    Create a context processor that adds both settings to every template context:

    ```python filename="myproject/context_processors.py"
    from django.conf import settings


    def rybbit(request):
        return {
            "RYBBIT_INSTANCE_URL": settings.RYBBIT_INSTANCE_URL,
            "RYBBIT_SITE_ID": settings.RYBBIT_SITE_ID,
        }
    ```

    Register it under `TEMPLATES` in `settings.py`:

    ```python filename="settings.py"
    TEMPLATES = [
        {
            "BACKEND": "django.template.backends.django.DjangoTemplates",
            "DIRS": [BASE_DIR / "templates"],
            "APP_DIRS": True,
            "OPTIONS": {
                "context_processors": [
                    "django.template.context_processors.request",
                    "django.contrib.auth.context_processors.auth",
                    "django.contrib.messages.context_processors.messages",
                    "myproject.context_processors.rybbit",
                ],
            },
        },
    ]
    ```

    #### Add the tag to your base template [#add-the-tag-to-your-base-template]

    Open the template that every page extends, usually `templates/base.html`, and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My Site{% endblock %}</title>

        {% if RYBBIT_SITE_ID %}
        <script src="{{ RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ RYBBIT_SITE_ID }}" defer></script>
        {% endif %}
    </head>
    ```

    The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable.

    Pages that do not `{% extends "base.html" %}` (for example a separate admin or landing template) need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: settings are read at startup, so restart the server (or your WSGI/ASGI workers) after changing `RYBBIT_SITE_ID`. Confirm the context processor path matches your project package name.
* **Template rendered without a request**: context processors only run for templates rendered with a `RequestContext`, which `render()` and class-based views provide. `Template.render()` without a request has no `RYBBIT_SITE_ID` and the guard hides the tag.
* **Content Security Policy**: if you use django-csp, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Docusaurus (/docs/guides/docusaurus)





Docusaurus has a `scripts` option in `docusaurus.config.js` that adds a `<script>` tag to the `<head>` of every page, so no theme swizzling is needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Docusaurus [#add-the-snippet-to-docusaurus]

    Open `docusaurus.config.js` (or `docusaurus.config.ts`) at the root of your project and add the script to the `scripts` array:

    ```javascript filename="docusaurus.config.js"
    /** @type {import('@docusaurus/types').Config} */
    const config = {
      // ... title, url, baseUrl, presets, themeConfig

      scripts: [
        {
          src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
          defer: true,
        },
      ],
    };

    module.exports = config;
    ```

    If you already manage tags through `headTags`, this form is equivalent:

    ```javascript filename="docusaurus.config.js"
    headTags: [
      {
        tagName: "script",
        attributes: {
          src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
          defer: "true",
        },
      },
    ],
    ```

    Rebuild with `npm run build` and deploy. The tag is not hot-reloaded into a running `npm run start` session until you restart it.

    <Callout type="info">
      Docusaurus builds a single-page app on React Router. Rybbit detects client-side route changes and records them as pageviews, so no extra code is needed for navigation.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Docusaurus pages are React, so you can fire events from a component and use it in MDX:

```jsx filename="src/components/TrackedButton.jsx"
import React from "react";

export default function TrackedButton({ children, eventName, eventData }) {
  const handleClick = () => {
    window.rybbit?.event(eventName, eventData);
  };

  return (
    <button onClick={handleClick} className="button button--primary">
      {children}
    </button>
  );
}
```

```mdx
import TrackedButton from "@site/src/components/TrackedButton";

<TrackedButton eventName="learn_more_clicked" eventData={{ page: "introduction" }}>
  Learn more
</TrackedButton>
```

For site-wide listeners, use a [client module](https://docusaurus.io/docs/advanced/client-modules). `onRouteDidUpdate` runs after every navigation once the DOM is ready:

```javascript filename="src/client-modules/rybbit-events.js"
export function onRouteDidUpdate() {
  document.querySelectorAll('a[target="_blank"]').forEach((link) => {
    link.addEventListener("click", () => {
      window.rybbit?.event("external_link_click", { href: link.href });
    });
  });
}
```

Register it in `docusaurus.config.js` under `clientModules: [require.resolve("./src/client-modules/rybbit-events.js")]`. Client modules also run during server-side rendering, so guard any `window` access.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Drupal (/docs/guides/drupal)





The [Rybbit module](https://www.drupal.org/project/rybbit) on Drupal.org adds the tracking script to every page and can pass logged-in user details to Rybbit, so you enter a Site ID instead of editing your theme. It requires Drupal 10.3 or later.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Drupal [#add-the-snippet-to-drupal]

    <Tabs items="[&#x22;Rybbit module&#x22;, &#x22;Theme template&#x22;]">
      <Tab>
        1. Install and enable the module:

           ```bash
           composer require drupal/rybbit
           drush en rybbit
           ```

        2. Go to **Configuration → Web services → Rybbit analytics** (`/admin/config/services/rybbit`). Your account needs the *administer rybbit* permission.

        3. Enter your **Site ID** and save.

        Optional settings on the same page:

        * **Script URL**: defaults to Rybbit cloud. Point it at your own instance if you self-host Rybbit.
        * **Visibility**: restrict tracking by role or by page path, each in include or exclude mode.
        * **Identify logged-in users**: calls `identify()` with the user's UUID by default, and sends traits you define as key/value pairs. `username`, `name` and `email` are recognised trait names.
        * The module also exposes hooks for altering the sitewide and per-user tracking data from your own module.
      </Tab>

      <Tab>
        If you cannot install contributed modules, copy `core/modules/system/templates/html.html.twig` into your theme's `templates` folder and add the snippet just before `</head>`:

        ```twig
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Clear caches afterwards so Drupal picks up the new template.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Script missing after saving settings**: pages are served from Drupal's page cache. Clear caches with `drush cr` or **Configuration → Development → Performance → Clear all caches**.
* **Visitors are tracked but you are not**: check the role and path visibility settings on the module page. Excluding the administrator role is a common setup.
* **Logged-in users appear anonymous**: enable **Identify logged-in users** in the module settings; without it Drupal accounts are tracked like any other visitor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Duda (/docs/guides/duda)





Duda has a site-wide **Header HTML** panel in the site settings with two fields: **Head HTML**, printed inside `<head>` on every page, and **Body End HTML**, printed before `</body>`. The snippet goes into Head HTML, and the site must be republished for it to reach the live site.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Duda [#add-the-snippet-to-duda]

    1. In the editor's side panel, click **More**, then **Settings**.
    2. Click **Header HTML**.
    3. Paste the snippet into **Head HTML** and click **Save**.
    4. **Republish** the site. Saved header code shows in the editor and preview, but the live site is only updated on republish.

    Head HTML accepts `<script>`, `<link>` and `<meta>` tags; anything else is stripped on save. The tracking snippet is a single `<script>` tag, so it is kept.

    To limit tracking to one page instead, open that page's **settings** (gear icon), click **SEO** and paste the snippet into that page's **Header HTML**.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the live page source**: the site was not republished. Republish after every change to Header HTML.
* **Code disappears after saving**: Head HTML strips tags other than `<script>`, `<link>` and `<meta>`. Paste only the script tag, without wrapping HTML or comments.
* **Consent management app in use**: Duda loads Head HTML before consent banners can intercept it. If you need the tracker gated by consent, put the snippet in **Body End HTML** instead, where the consent app can control it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ecwid (/docs/guides/ecwid)





An Ecwid by Lightspeed store runs either on Ecwid's hosted **Instant Site** or embedded in a page on another platform. On Instant Site the snippet goes into the site's header code setting; for an embedded store it goes into the `<head>` of the host site, and the storefront Ecwid renders inside that page is tracked with it.

<Callout type="warn">
  Custom code on Instant Site is available on the **Venture**, **Business** and **Unlimited** plans. The free Starter plan has no custom code fields.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ecwid [#add-the-snippet-to-ecwid]

    <Tabs items="[&#x22;Instant Site&#x22;, &#x22;Embedded store&#x22;]">
      <Tab>
        1. From your Ecwid admin, go to **Website** (or **Overview → Manage Instant Site**).
        2. Scroll down to **SEO settings** and click **Add Code** under **Header meta tags and site verification**.
        3. Paste the snippet and save.
        4. Reload your Instant Site in the browser; there is no separate publish step for this setting.

        The **Custom JavaScript code** field under **Advanced website settings** on the same page also works, but it prints code at the end of `<body>`, so prefer the header field.
      </Tab>

      <Tab>
        The store is rendered by Ecwid's embed script inside your own page, so add the snippet to the `<head>` of the host site with that platform's method. See the [integration guides](/docs/guides) for WordPress, Wix, Squarespace, Webflow and others.

        One snippet covers the whole store: product pages, cart and checkout all render inside the same host page.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Ecwid's storefront JavaScript API fires `Ecwid.OnOrderPlaced` with the order right after a customer places it. Add this where the `Ecwid` object already exists: on Instant Site, under **Advanced website settings → Custom JavaScript code**; on an embedded store, after the Ecwid embed script on the host page.

```html
<script>
Ecwid.OnAPILoaded.add(function () {
  Ecwid.OnOrderPlaced.add(function (order) {
    window.rybbit.event('purchase', {
      transaction_id: order.vendorNumber,
      value: order.total,
      tax: order.tax,
      shipping: order.shipping,
      items: order.items.map(function (item) {
        return { item_id: item.sku, item_name: item.name, price: item.price, quantity: item.quantity };
      })
    });
  });
});
</script>
```

`vendorNumber` is the order number customers see in emails; `orderNumber` is Ecwid's internal ID. Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.

Ecwid also has a **Custom tracking code on Order Confirmation page** field under **Settings → General → Tracking & Analytics** (same plans as above). Code there runs on the `/checkout/order-confirmation` page and can use Ecwid's template variables when wrapped in `<#noescape>`:

```html
<script>
<#noescape>
document.addEventListener('DOMContentLoaded', function () {
  window.rybbit.event('purchase', { transaction_id: "${order.number}", value: ${order.total} });
});
</#noescape>
</script>
```

Use one method or the other, not both, or every order is counted twice.

## Troubleshooting [#troubleshooting]

* **No Add Code button under SEO settings**: the store is on the Starter plan. Custom code needs Venture or higher.
* **`Ecwid is not defined`**: the purchase snippet ran before Ecwid's script. Move it below the embed script, or keep it in the Instant Site **Custom JavaScript code** field, which runs at the end of the page.
* **Embedded store, no pageviews**: the snippet belongs to the host site, not to Ecwid. Check the host page's source for `script.js?siteId=`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Electron (/docs/guides/electron)





An Electron renderer is a Chromium page, so Rybbit runs in it the same way it runs in a browser. For a renderer built with a bundler (Vite, webpack, the Electron Forge templates) install the `@rybbit/js` SDK and initialise it in the renderer entry file; for a plain HTML renderer put the snippet in the `<head>` of the HTML file the window loads. In both cases allow `https://app.rybbit.io` in the renderer's Content Security Policy.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Electron [#add-the-snippet-to-electron]

    <Tabs items="[&#x22;@rybbit/js SDK&#x22;, &#x22;Script tag&#x22;]">
      <Tab>
        The SDK is bundled with your renderer code, so nothing is loaded from a CDN at runtime and `script-src 'self'` stays intact.

        1. Install the package in your project:

        ```bash
        npm install @rybbit/js
        ```

        2. Initialise it once in the renderer entry file, before any other tracking call:

        ```js title="src/renderer.js"
        import rybbit from "@rybbit/js";

        await rybbit.init({
          analyticsHost: "https://app.rybbit.io/api",
          siteId: "YOUR_SITE_ID",
        });
        ```

        3. Allow the analytics host in `connect-src`. Electron recommends a CSP for every renderer; when the renderer is loaded from a file, HTTP headers are not available, so use the meta tag:

        ```html title="src/index.html"
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'self'; connect-src 'self' https://app.rybbit.io"
        />
        ```
      </Tab>

      <Tab>
        Paste the snippet into the `<head>` of the renderer HTML and allow the host in both `script-src` (the script itself) and `connect-src` (its requests):

        ```html title="src/index.html"
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'self'; script-src 'self' https://app.rybbit.io; connect-src 'self' https://app.rybbit.io"
        />
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        If you set the CSP from the main process with `session.defaultSession.webRequest.onHeadersReceived` instead, add the same two sources there.
      </Tab>
    </Tabs>

    Both methods track in-app navigation without extra code: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so history-mode and hash-mode routers are covered.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Requests are blocked on the `file://` origin**: Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only. A renderer opened with `win.loadFile()` runs on the `file://` origin and sends `Origin: null`, so Chromium blocks the `POST` to `/api/track` before it leaves the app. The same applies to custom schemes registered with `protocol.handle()`. Load the renderer over http(s) with `win.loadURL()` (your dev server in development, a hosted or locally served build in production) and tracking works.
* **Console shows a CSP violation**: the message names the directive that blocked the request. Add `https://app.rybbit.io` to that directive; `connect-src` covers the SDK, and the script tag also needs `script-src`.
* **Hostname is empty in the dashboard**: pageviews report the renderer's `window.location.hostname`, which is empty for `file://` pages. Filter by site rather than hostname.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Eleventy (/docs/guides/eleventy)





Eleventy renders every page through a layout in `_includes/`, so the snippet goes in your base layout's `<head>`. Keep the site ID in a global data file under `_data/` so the layout stays free of hard-coded values.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Eleventy [#add-the-snippet-to-eleventy]

    1. Create `_data/rybbit.json` (create the `_data/` directory if it does not exist). Every template can then read it as `rybbit`. Change `instanceUrl` only if you self-host:

       ```json title="_data/rybbit.json"
       {
         "siteId": "YOUR_SITE_ID",
         "instanceUrl": "https://app.rybbit.io"
       }
       ```

    2. Open your base layout and add the tag inside `<head>`. The `eleventy.env.runMode` check keeps the script out of `--serve` and `--watch` runs, so local development is not tracked; the `rybbit.siteId` check keeps it out of builds with no ID configured.

    <Tabs items="[&#x22;Nunjucks&#x22;, &#x22;Liquid&#x22;]">
      <Tab value="Nunjucks">
        ```html title="_includes/base.njk"
        <head>
          ...
          {% if eleventy.env.runMode == "build" and rybbit.siteId %}
            <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>

      <Tab value="Liquid">
        ```html title="_includes/base.liquid"
        <head>
          ...
          {% if eleventy.env.runMode == "build" and rybbit.siteId %}
            <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>
    </Tabs>

    3. Build and deploy the generated `_site/` directory:

       ```bash
       npx @11ty/eleventy
       ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `npx @11ty/eleventy --serve` sets `runMode` to `serve`, so the guard removes the tag. Check the output of a plain build instead.
* **Eleventy 1.x**: `eleventy.env.runMode` was added in Eleventy 2.0. On older versions drop the `runMode` condition and keep only the `rybbit.siteId` check.
* **Custom data directory**: if your config sets `dir.data`, put `rybbit.json` in that directory instead of `_data/`.
* **Several layouts**: a page only gets the tag if its layout chain ends in the layout you edited. Pages with `layout: none` or a different base layout need the tag added there too.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ember (/docs/guides/ember)





An Ember app has one HTML shell that every route renders into. Apps created with the current Vite-based `ember new` blueprint keep it at `index.html` in the project root; classic ember-cli apps keep it at `app/index.html`. Paste the snippet into the `<head>` of that file.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ember [#add-the-snippet-to-ember]

    Open `index.html` (or `app/index.html` in a classic ember-cli app) and paste the snippet inside `<head>`, after the `{{content-for "head"}}` placeholder:

    ```handlebars title="index.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8">
        <title>MyApp</title>
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        {{content-for "head"}}

        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

        <link integrity="" rel="stylesheet" href="/@embroider/virtual/vendor.css">
        <link integrity="" rel="stylesheet" href="/@embroider/virtual/app.css">

        {{content-for "head-footer"}}
      </head>
      <body>
        {{content-for "body"}}
        ...
        {{content-for "body-footer"}}
      </body>
    </html>
    ```

    Keep the `{{content-for}}` placeholders in place; the build fills them in. Route transitions made by Ember's router (the default `history` location type) are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a component action. Guard the call so a blocked or still-loading script does not throw.

```js title="app/components/signup-button.gjs"
import Component from "@glimmer/component";
import { on } from "@ember/modifier";

export default class SignupButton extends Component {
  trackSignup = () => {
    if (window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  <template>
    <button type="button" {{on "click" this.trackSignup}}>Sign up</button>
  </template>
}
```

## Troubleshooting [#troubleshooting]

* **`index.html` is also used by the test runner**: `tests/index.html` is a separate file. Do not add the snippet there, or test runs send pageviews to your dashboard.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# FastAPI (/docs/guides/fastapi)





FastAPI serves HTML through `Jinja2Templates`, so the snippet goes into the `<head>` of the base template your pages extend. Keep the site ID in a `pydantic-settings` class and register it as a Jinja global so every template can render the tag without passing it through each route.

<Callout type="info">
  The tracking script runs in a browser, so it only applies to routes that return template-rendered HTML. JSON endpoints have nothing for it to track.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to FastAPI [#add-the-snippet-to-fastapi]

    #### Configure the site ID [#configure-the-site-id]

    Install `pydantic-settings` and `jinja2` if you have not already:

    ```bash
    pip install pydantic-settings jinja2
    ```

    Define the settings, reading from the environment and an optional `.env` file:

    ```python filename="config.py"
    from pydantic_settings import BaseSettings, SettingsConfigDict


    class Settings(BaseSettings):
        model_config = SettingsConfigDict(env_file=".env")

        rybbit_instance_url: str = "https://app.rybbit.io"
        rybbit_site_id: str = ""


    settings = Settings()
    ```

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    #### Register the values with Jinja [#register-the-values-with-jinja]

    `Jinja2Templates` exposes its environment as `templates.env`, so add the settings as globals once, next to where you create the templates object:

    ```python filename="main.py"
    from fastapi import FastAPI, Request
    from fastapi.responses import HTMLResponse
    from fastapi.templating import Jinja2Templates

    from config import settings

    app = FastAPI()
    templates = Jinja2Templates(directory="templates")
    templates.env.globals["rybbit_instance_url"] = settings.rybbit_instance_url
    templates.env.globals["rybbit_site_id"] = settings.rybbit_site_id


    @app.get("/", response_class=HTMLResponse)
    async def index(request: Request):
        return templates.TemplateResponse(request=request, name="index.html")
    ```

    #### Add the tag to your base template [#add-the-tag-to-your-base-template]

    Open the template your pages extend, usually `templates/base.html`, and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My App{% endblock %}</title>

        {% if rybbit_site_id %}
        <script src="{{ rybbit_instance_url }}/api/script.js?siteId={{ rybbit_site_id }}" defer></script>
        {% endif %}
    </head>
    ```

    The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable. Templates that do not extend the base need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `Settings()` reads the environment when the module is imported, so restart Uvicorn (or your process manager) after changing `RYBBIT_SITE_ID`.
* **Several `Jinja2Templates` instances**: globals are per environment. If routers create their own `Jinja2Templates`, set the globals on each, or share one instance from a module.
* **Content Security Policy**: if middleware sets one, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Flask (/docs/guides/flask)





Flask renders Jinja templates, and most apps extend a shared base layout, so the snippet goes into that layout's `<head>`. Flask exposes `app.config` to every template as `config`, so store the site ID there and reference it from the template.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Flask [#add-the-snippet-to-flask]

    #### Configure the site ID [#configure-the-site-id]

    Flask loads any environment variable prefixed with `FLASK_` into `app.config` when you call `from_prefixed_env()`. Set the values in your environment (`flask run` also reads a `.env` file when python-dotenv is installed):

    ```bash filename=".env"
    FLASK_RYBBIT_INSTANCE_URL=https://app.rybbit.io
    FLASK_RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then load them where you create the app:

    ```python filename="app.py"
    from flask import Flask, render_template

    app = Flask(__name__)
    app.config.setdefault("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
    app.config.from_prefixed_env()


    @app.route("/")
    def index():
        return render_template("index.html")
    ```

    `from_prefixed_env()` parses values as JSON where it can, so a numeric site ID arrives as an `int`. It renders the same in the template.

    If you keep configuration in a Python file or class instead, add `RYBBIT_INSTANCE_URL` and `RYBBIT_SITE_ID` there and load it with `app.config.from_object()`.

    #### Add the tag to your base layout [#add-the-tag-to-your-base-layout]

    Open the template that your pages extend, usually `templates/base.html` (or `templates/layout.html`), and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My App{% endblock %}</title>

        {% if config.RYBBIT_SITE_ID %}
        <script src="{{ config.RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ config.RYBBIT_SITE_ID }}" defer></script>
        {% endif %}
    </head>
    ```

    `config` is part of Flask's standard template context, so no context processor is needed. The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is unset, so local development is not tracked unless you set the variable.

    Templates that do not extend the base layout need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `from_prefixed_env()` reads the environment when the app is created, so restart the server after changing `FLASK_RYBBIT_SITE_ID`. Check `app.config["RYBBIT_SITE_ID"]` in `flask shell`.
* **Macros imported into other templates**: `config` is added to the render context, not to imported templates. A macro that outputs the tag must be imported `with context`.
* **Content Security Policy**: if you set one with Flask-Talisman or similar, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `FLASK_RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Flutter web (/docs/guides/flutter-web)





A Flutter web app is served from the `web/index.html` template in your project, which `flutter build web` copies to `build/web/index.html`. The snippet goes in that file's `<head>`. Flutter draws the UI into a canvas rather than DOM elements, so pageviews and manual events work as usual while anything that inspects the DOM does not.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Flutter web [#add-the-snippet-to-flutter-web]

    1. Open `web/index.html` in your Flutter project.
    2. Paste the snippet inside `<head>`, above the `flutter_bootstrap.js` script that Flutter generates:

    ```html title="web/index.html"
    <head>
      <meta charset="UTF-8" />
      <title>My App</title>
      <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    ```

    3. Rebuild with `flutter build web` and deploy the `build/web` folder.

    Navigation is tracked automatically with either URL strategy. Flutter's default hash strategy writes routes as `/#/settings`, and the tracker listens for `hashchange` and records `#/settings` as the path `/settings`. With `usePathUrlStrategy()` the Navigator uses the History API, and the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Flutter widgets are not HTML elements, so `data-rybbit-event` attributes have nothing to attach to. Call `window.rybbit.event()` from Dart through `dart:js_interop` instead:

```dart title="lib/analytics.dart"
import 'dart:js_interop';

@JS('rybbit.event')
external void _rybbitEvent(String name, [JSAny? properties]);

void trackEvent(String name, [Map<String, Object?>? properties]) {
  _rybbitEvent(name, properties?.jsify());
}
```

```dart
ElevatedButton(
  onPressed: () {
    trackEvent('signup_click', {'plan': 'pro'});
  },
  child: const Text('Sign up'),
)
```

Guard the call with `kIsWeb` if the same code also compiles for mobile or desktop targets.

## Troubleshooting [#troubleshooting]

* **Clicks, outbound links and session replay show nothing**: the CanvasKit and Skwasm renderers paint into a single `<canvas>`, so DOM-based features (`data-rybbit-event` attributes, outbound-link tracking, button-click autocapture, session replay) have no elements to observe. Use the Dart interop above for events.
* **Deep links 404 after switching to `usePathUrlStrategy()`**: path URLs need the web server to rewrite every route to `index.html`; the Flutter dev server does this for you, production hosting must be configured.
* **`rybbit` is undefined in Dart**: the snippet is `defer`red, so it is not ready during `main()`. Send events from user interactions, not from app start-up.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Framer (/docs/guides/framer)





Framer has a **Custom Code** section in the site settings that injects HTML into the `<head>` of every published page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Framer [#add-the-snippet-to-framer]

    1. Open your Framer project and go to **Site Settings → General**.
    2. Scroll to **Custom Code**.
    3. Paste the snippet into the **Start of `<head>` tag** field (End of `<head>` works too).
    4. Click **Save**, then **Publish**. Custom code only reaches the live site on publish.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Use a **Code Override** to send events from any element in the canvas.

1. Select the element, open **Overrides*&#x2A; in the properties panel, and click **+ File** to create an override file such as `RybbitOverrides.tsx`.
2. Add an override that wraps the element's click handler:

```tsx
// RybbitOverrides.tsx
import type { ComponentType } from "react";

export function withRybbitClick(Component: ComponentType): ComponentType {
  return (props) => {
    const handleClick = () => {
      window.rybbit?.event("cta_click", { label: props.text ?? "cta" });
      props.onClick?.();
    };
    return <Component {...props} onClick={handleClick} />;
  };
}
```

3. Back in the properties panel, pick the file and apply `withRybbitClick` to the element.

The same `window.rybbit.event()` call works inside a **Code Component**.

## Troubleshooting [#troubleshooting]

* **Navigation between pages is not tracked**: Framer sites navigate client-side and the script detects those URL changes. If a view changes without the URL changing, call `window.rybbit.pageview()` from an override when it appears.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Fumadocs (/docs/guides/fumadocs)





Fumadocs is a documentation framework for Next.js, so the snippet goes in the root layout, `app/layout.tsx`, rendered with `next/script` so it is on every page including the docs routes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Fumadocs [#add-the-snippet-to-fumadocs]

    Open `app/layout.tsx` and render the `Script` component inside `<body>`, next to the `RootProvider` that Fumadocs already puts there:

    ```tsx title="app/layout.tsx"
    import { RootProvider } from "fumadocs-ui/provider/next";
    import Script from "next/script";
    import type { ReactNode } from "react";

    export default function Layout({ children }: { children: ReactNode }) {
      return (
        <html lang="en" suppressHydrationWarning>
          <body className="flex flex-col min-h-screen">
            <RootProvider>{children}</RootProvider>
            <Script
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    Use the root layout, not `app/docs/layout.tsx`: the docs layout only wraps pages under `/docs`, so a landing page outside it would be missed.

    Client-side navigation between docs pages is recorded as pageviews automatically. The [Next.js guide](/docs/guides/react/next-js) covers the `Script` component, custom events from client components and proxying through your own domain.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ghost (/docs/guides/ghost)





Ghost has a built-in **Code injection** setting that adds HTML to the `<head>` of every page, so no theme edits are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ghost [#add-the-snippet-to-ghost]

    1. Open **Ghost Admin** and click the **Settings** gear in the bottom left.
    2. Under **Advanced**, open **Code injection**.
    3. Paste the snippet into **Site header** and click **Save**.

    If you maintain your own theme instead, add the snippet to `default.hbs` just before `</head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Ghost(Pro) with a custom theme**: code injection still applies on top of the theme, so prefer it over editing `default.hbs`.
* **Member-only content**: pages behind the paywall are tracked like any other page for visitors who can view them.
* **Portal and newsletter previews** render in an iframe and are not tracked.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# GitBook (/docs/guides/gitbook)





GitBook does not let you add custom scripts to a published site, and its integration platform does not let third parties inject them either. This page explains what that means and what your options are.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to GitBook [#add-the-snippet-to-gitbook]

    <Callout type="warn">
      There is currently no supported way to load the Rybbit snippet on a GitBook-hosted site. The old **Custom scripts → Head** setting was removed, and GitBook's [integration scopes](https://gitbook.com/docs/developers/integrations/configurations) reserve `site:script:inject` for GitBook's own integrations: "Building integrations that inject JavaScript into a site or space is not possible at this time."
    </Callout>

    Your options:

    * **Use GitBook's built-in analytics.** The **Insights** section in the GitBook app reports page views and search terms for published sites without any script.
    * **Wait for a native integration.** A Rybbit integration would need GitBook to build or approve it. Ask GitBook support for it, and watch the [Rybbit roadmap](/docs/roadmap).
    * **Host the docs elsewhere.** [Docusaurus](/docs/guides/docusaurus), [Mintlify](/docs/guides/mintlify), [VitePress](/docs/guides/vitepress), [Starlight](/docs/guides/starlight) and [Fumadocs](/docs/guides/fumadocs) all take the snippet directly, and GitBook can export a space as Markdown to migrate.

    The rest of your site (marketing pages, app, blog) is unaffected: add the snippet there as usual so traffic from the docs is still attributed by referrer.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Google Tag Manager (/docs/guides/google-tag-manager)





Google Tag Manager loads Rybbit through a **Custom HTML** tag fired on **All Pages**, so nothing in your site's code changes. Events you already push to the `dataLayer` can be forwarded to Rybbit with a second tag.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Google Tag Manager [#add-the-snippet-to-google-tag-manager]

    1. Open your GTM container and go to **Tags → New**.
    2. Under **Tag Configuration**, choose **Custom HTML** and paste the snippet:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    3. Under **Triggering**, choose **All Pages** (the built-in Page View trigger).
    4. Name the tag, for example `Rybbit - Loader`, and click **Save**.
    5. Click **Submit** and publish the container version.

    <Callout type="warn">
      GTM rebuilds Custom HTML tags before injecting them and can drop non-standard attributes. Keep the site ID in the URL (`?siteId=`) as shown; the older `data-*` attribute form is not reliable here.
    </Callout>

    Use **Preview** mode to confirm the tag fires on page load before publishing.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Once the loader tag is published, `window.rybbit` is available to your own JavaScript and to other GTM tags.

#### Forward dataLayer events [#forward-datalayer-events]

If your site already pushes events like `dataLayer.push({ event: "signup" })`, one tag can forward them to Rybbit:

1. Create a **Custom Event** trigger. Set the event name to a regex such as `signup|purchase|add_to_cart` (tick **Use regex matching**).
2. Create a **Custom HTML** tag with that trigger:

```html
<script>
  if (window.rybbit) {
    window.rybbit.event("{{Event}}", {
      page: "{{Page Path}}",
      referrer: "{{Referrer}}"
    });
  }
</script>
```

`{{Event}}`, `{{Page Path}}` and `{{Referrer}}` are GTM built-in variables. Add a **Data Layer Variable** for any custom field you push (for example `plan`) and reference it the same way.

#### Use GTM's click and form triggers [#use-gtms-click-and-form-triggers]

The same pattern works with built-in **Click** and **Form Submission** triggers:

```html
<script>
  if (window.rybbit) {
    window.rybbit.event("cta_clicked", {
      text: "{{Click Text}}",
      url: "{{Click URL}}"
    });
  }
</script>
```

Enable the **Click Text** and **Click URL** built-in variables under **Variables → Configure**.

## Troubleshooting [#troubleshooting]

* **Event tag fires before Rybbit loads**: the loader script is deferred, so an event tag on the same page load may run first and hit the `if (window.rybbit)` guard. Open the event tag's **Advanced Settings → Tag Sequencing** and set the loader tag to fire before it, or trigger the event tag on **Window Loaded** instead of **Page View**.
* **Consent mode**: if your container gates tags on consent, add the loader tag to the same consent group as your other analytics tags, otherwise it never fires.
* **Tag shows in Preview but not live**: the container version was not published. Click **Submit** and publish.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hexo (/docs/guides/hexo)





Hexo 5 and later ship an injector API that adds HTML to the `<head>` of every generated page from a small file in your site's `scripts/` directory, so no theme edits are needed. Editing the theme's head partial is the fallback for older versions.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hexo [#add-the-snippet-to-hexo]

    <Tabs items="[&#x22;Injector script&#x22;, &#x22;Theme layout&#x22;]">
      <Tab value="Injector script">
        1. Add your site ID to the site `_config.yml` at the root of your project (not the theme config). `instance_url` is only needed if you self-host:

           ```yaml title="_config.yml"
           rybbit:
             site_id: "YOUR_SITE_ID"
             instance_url: "https://app.rybbit.io"
           ```

        2. Create `scripts/rybbit.js` (create the `scripts/` directory if it does not exist). Hexo loads every file in this directory at startup with the `hexo` object in scope:

           ```javascript title="scripts/rybbit.js"
           const { site_id: siteId, instance_url: instanceUrl = "https://app.rybbit.io" } =
             hexo.config.rybbit || {};

           if (siteId) {
             hexo.extend.injector.register(
               "head_end",
               `<script src="${instanceUrl}/api/script.js?siteId=${siteId}" defer></script>`
             );
           }
           ```

           `head_end` places the tag right before `</head>`. With no third argument the injector applies to every page type.
      </Tab>

      <Tab value="Theme layout">
        Open your theme's head partial and paste the snippet before `</head>`. For the default Landscape theme that file is `themes/landscape/layout/_partial/head.ejs`; other themes keep an equivalent partial under `layout/`.

        ```html title="themes/landscape/layout/_partial/head.ejs"
          ...
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Theme updates overwrite this file, so prefer the injector when your Hexo version supports it.
      </Tab>
    </Tabs>

    Regenerate and deploy the `public/` directory:

    ```bash
    hexo clean && hexo generate
    ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **`hexo.extend.injector` is undefined**: the injector API arrived in Hexo 5.0. Check `hexo version` and upgrade, or use the theme layout method.
* **Tag missing after adding the script**: run `hexo clean` before `hexo generate`; Hexo caches rendered output in `db.json` and can serve stale pages.
* **Local previews are tracked**: `hexo server` runs the same injector as `hexo generate`. Leave `site_id` empty in a local copy of `_config.yml`, or accept the local pageviews.
* **Theme config vs site config**: `hexo.config` reads the root `_config.yml`, not `themes/<name>/_config.yml`. Put the `rybbit` block in the root file.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hostinger Website Builder (/docs/guides/hostinger)





Hostinger Website Builder has a **Custom code** integration in the website settings that adds code to every page. Script tags are placed at the end of `<body>` by default; a `data-render-head` attribute moves them into `<head>`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hostinger Website Builder [#add-the-snippet-to-hostinger-website-builder]

    1. Open your site in the builder and click &#x2A;*⋯** (More) at the top to open the website settings, then choose **Integrations**.
    2. Select **Custom code**.
    3. Paste the snippet with `data-render-head` added so it loads from `<head>`:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer data-render-head></script>
    ```

    4. Save the changes, then click **Update website** to publish. Custom code runs on the live site and in preview, not inside the editor.

    Without `data-render-head` the builder moves `<script>` tags to the end of `<body>`. The tracker still works there; the attribute only makes it load earlier.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **No requests to `script.js` in the editor**: expected. Integrations are injected into the published site only, so check the live URL or the preview.
* **Snippet saved but not in the page source**: the site was not updated after saving. Click **Update website**.
* **Site breaks after adding several snippets**: paste snippets one after another, never nested inside each other. If the page still fails, remove all custom code, update, and add the snippets back one at a time.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# htmx (/docs/guides/htmx)





htmx pages are plain server-rendered HTML, so the snippet goes in the `<head>` of your base layout next to the htmx script tag, in whichever template your server uses for the full-page response.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to htmx [#add-the-snippet-to-htmx]

    Open the template that renders the full HTML document (the one that already loads htmx) and paste the snippet inside `<head>`:

    ```html title="layout.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My htmx App</title>
        <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.10/dist/htmx.min.js"></script>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <main id="content" hx-boost="true">...</main>
      </body>
    </html>
    ```

    Only full-page responses need the tag. Partial responses that htmx swaps into the page must not include it, or the script is re-evaluated on every swap.

    Navigations that htmx records in browser history are tracked automatically as pageviews: `hx-push-url` and `hx-boost` call `history.pushState()`, `hx-replace-url` calls `history.replaceState()`, and the back and forward buttons fire `popstate`. All three are hooked by the tracker. A swap without `hx-push-url` leaves the URL unchanged and is not counted as a pageview; send a [custom event](/docs/track-events) for those interactions instead.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Use the `data-rybbit-event` attribute on the element that triggers the request. The tracker listens for clicks on `document`, so it also works on content that htmx swapped in after the page loaded:

```html
<button
  hx-post="/subscribe"
  hx-target="#form"
  data-rybbit-event="newsletter_subscribe"
  data-rybbit-prop-plan="free"
>
  Subscribe
</button>
```

To record an event when the server has actually processed the request, listen for htmx's `htmx:afterRequest` event and call `window.rybbit.event()` from there.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# HubSpot (/docs/guides/hubspot)





HubSpot Content Hub (formerly CMS Hub) has a **Site header HTML** setting that injects code into the `<head>` of every website page, landing page, blog post and knowledge base article on a domain, so no template edits are needed. Individual pages can add or override code from the content editor.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to HubSpot [#add-the-snippet-to-hubspot]

    <Tabs items="[&#x22;Site header HTML&#x22;, &#x22;Single page&#x22;]">
      <Tab>
        This adds the snippet to all HubSpot-hosted content on a domain.

        1. In your HubSpot account, click the **settings** icon in the top navigation bar.
        2. In the left sidebar, go to **Content > Pages**.
        3. Use the **Choose a domain to edit its settings** dropdown to pick the domain, or stay on the default settings to apply the code to every domain.
        4. Paste the snippet into the **Site header HTML** field.
        5. Click **Save**.

        If a domain has **Override default settings** turned on, the default header code no longer applies to it. Add the snippet to that domain's own settings as well.
      </Tab>

      <Tab>
        Use this to track a single page, or when someone else controls the domain settings.

        1. Open **Content > Website Pages** (or **Landing Pages**, **Blog**, **Knowledge Base**) and click the page name to open the editor.
        2. Click the **Settings** menu, then select **Advanced**.
        3. Under **Additional code snippets**, paste the snippet into the **Head HTML** field.
        4. Click **Update** or **Publish**.

        Per-page head HTML is added on top of the site header HTML, so a page tracked by both methods loads the script twice. Pick one.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

HubSpot forms submit inside the page without a full reload, so track them with a custom event. Add `data-rybbit-event` to a call-to-action button, or listen for HubSpot's form-submitted message in a small script placed after the snippet:

```html
<script>
  window.addEventListener("message", function (event) {
    if (event.data.type === "hsFormCallback" && event.data.eventName === "onFormSubmitted") {
      window.rybbit.event("form_submitted", { formId: event.data.id });
    }
  });
</script>
```

See [Track custom events](/docs/track-events) for the event API.

## Troubleshooting [#troubleshooting]

* **Snippet missing on one domain**: the site header HTML is per domain. Check whether that domain has **Override default settings** enabled and add the snippet there.
* **Duplicate pageviews**: the same page has the snippet in both site header HTML and its own **Head HTML**. Remove one.
* **Editor and preview**: the content editor renders pages in an iframe with unpublished changes. Previews are tracked like any other visit if they load the script, so avoid checking analytics from the editor.
* **Quotes**: header HTML set at the domain level also loads on HubSpot quotes hosted on that domain.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hugo (/docs/guides/hugo)





Hugo builds every page from templates under `layouts/`, so the cleanest place for the snippet is a partial template that your base template includes on every page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hugo [#add-the-snippet-to-hugo]

    1. Add your site ID under `params` in your Hugo config (`hugo.toml`, or `config.toml` in older Hugo versions). `rybbitInstanceURL` is only needed if you self-host:

       ```toml title="hugo.toml"
       [params]
         rybbitSiteID = "YOUR_SITE_ID"
         rybbitInstanceURL = "https://app.rybbit.io"
       ```

    2. Create `layouts/partials/rybbit-analytics.html` (create the `layouts/partials/` directory if it does not exist):

       ```html title="layouts/partials/rybbit-analytics.html"
       {{ if and (not hugo.IsServer) .Site.Params.rybbitSiteID }}
         <script src="{{ .Site.Params.rybbitInstanceURL | default "https://app.rybbit.io" }}/api/script.js?siteId={{ .Site.Params.rybbitSiteID }}" defer></script>
       {{ end }}
       ```

       `not hugo.IsServer` skips the script during `hugo server`, so local development is not tracked. The `rybbitSiteID` check keeps the tag out of builds that have no ID configured.

    3. Include the partial from your base template, typically `layouts/_default/baseof.html`, inside `<head>`. If your theme owns `baseof.html`, copy it into your project's `layouts/_default/` first so the theme can be updated without losing the change; a theme footer partial such as `layouts/partials/footer.html` also works.

       ```html title="layouts/_default/baseof.html"
       <head>
         ...
         {{ partial "rybbit-analytics.html" . }}
       </head>
       ```

    4. Build with `hugo` and deploy the generated `public/` directory.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `hugo server` never emits it because of the `hugo.IsServer` guard. Check the output of a production `hugo` build instead.
* **Theme overrides**: a file at `layouts/_default/baseof.html` in your project takes precedence over the theme's copy, so make sure you edited the one Hugo actually renders.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Integration guides (/docs/guides)



Rybbit works on any site that can load a script tag. Each guide below shows exactly where the tracking snippet goes on that platform and how to confirm it is working.

Don't see your platform? Paste the snippet from **Site Settings → Tracking Script** into the `<head>` of every page, or follow the [tracking script](/docs/script) reference.

<GuideIndex />


# Instapage (/docs/guides/instapage)





Instapage takes custom scripts at two levels: **Workspace scripts** (under **Assets > Scripts**) apply to every page in a workspace, and each page also has its own **JavaScript** and **HTML/CSS** settings with a **Head** section. Custom HTML, CSS and JavaScript are included on all Instapage plans; Workspace scripts are limited to some subscriptions and show an upgrade prompt otherwise.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Instapage [#add-the-snippet-to-instapage]

    <Tabs items="[&#x22;Workspace scripts&#x22;, &#x22;Single page&#x22;]">
      <Tab>
        1. In the left menu, open **Assets**, then **Scripts**.
        2. Paste the snippet into the **Head** section.
        3. Above the editor, choose how it applies: option **A** adds it to every past and future page in the workspace; **B** leaves it off until you switch it on per page under **Scripts & Privacy**; **B + C** turns it on for all pages but lets you disable it per page.
        4. Click **Apply**.

        Workspace scripts load on the live URL before any page-level script, so the snippet is in place before other code on the page runs.
      </Tab>

      <Tab>
        1. Open the page in the builder and click **Settings** in the right sidebar.
        2. Open the **HTML/CSS** tab and paste the snippet into **Head**. (The **JavaScript** tab has the same three sections and wraps your code in `<script>` tags automatically; the snippet already has its own tag, so HTML/CSS is the simpler choice.)
        3. **Publish** the page. Custom code runs only on the live, published page, not in the editor or preview.
      </Tab>
    </Tabs>

    <Callout type="info">
      If you use Instapage's privacy compliance banner, put the snippet in the page's **Scripts & Privacy** section instead so it fires only after the visitor accepts.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: the page was saved but not republished. Custom code only reaches the live URL on publish.
* **Assets > Scripts shows an upgrade prompt**: Workspace scripts are not on your subscription. Add the snippet per page instead.
* **Duplicate pageviews**: the snippet is both a workspace script and a page-level script. Keep one copy.
* **Old version still served**: clear your browser cache after publishing; Instapage notes cached copies can outlive an update.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Jekyll (/docs/guides/jekyll)





Jekyll renders every page through a layout, usually `_layouts/default.html`. Put the snippet in an include file that the layout pulls in, or paste it into the layout directly.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Jekyll [#add-the-snippet-to-jekyll]

    <Tabs items="[&#x22;Include file&#x22;, &#x22;Layout file&#x22;]">
      <Tab value="Include file">
        1. Add your site ID to `_config.yml`. `rybbit_instance_url` is only needed if you self-host:

           ```yaml title="_config.yml"
           rybbit_site_id: "YOUR_SITE_ID"
           rybbit_instance_url: "https://app.rybbit.io"
           ```

        2. Create `_includes/rybbit-analytics.html` (create the `_includes/` directory if it does not exist):

           ```html title="_includes/rybbit-analytics.html"
           {% if jekyll.environment == "production" and site.rybbit_site_id %}
             <script src="{{ site.rybbit_instance_url | default: 'https://app.rybbit.io' }}/api/script.js?siteId={{ site.rybbit_site_id }}" defer></script>
           {% endif %}
           ```

           The `jekyll.environment` check keeps the script out of local `jekyll serve` builds; the `site.rybbit_site_id` check keeps it out of builds with no ID configured.

        3. Include it from your layout's `<head>`:

           ```html title="_layouts/default.html"
           <head>
             ...
             {% include rybbit-analytics.html %}
           </head>
           ```
      </Tab>

      <Tab value="Layout file">
        Open `_layouts/default.html` and paste the snippet inside `<head>`, wrapped in a production check so local `jekyll serve` builds are not tracked:

        ```html title="_layouts/default.html"
        <head>
          ...
          {% if jekyll.environment == "production" %}
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>
    </Tabs>

    Build for production and deploy the generated `_site/` directory:

    ```bash
    JEKYLL_ENV=production jekyll build
    ```

    GitHub Pages sets `jekyll.environment` to `production` during its own build, so no extra configuration is needed there.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `jekyll serve` and a plain `jekyll build` run with `jekyll.environment` set to `development`, so the production guard removes the tag. Build with `JEKYLL_ENV=production` and check that output.
* **Config changes not applied**: Jekyll reads `_config.yml` once at startup, so restart `jekyll serve` after adding `rybbit_site_id`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Joomla (/docs/guides/joomla)





Joomla has no built-in head-code setting, so the snippet goes in either a **Custom** module assigned to every page or in your template's `index.php`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Joomla [#add-the-snippet-to-joomla]

    <Tabs items="[&#x22;Custom module&#x22;, &#x22;Template file&#x22;]">
      <Tab>
        No file edits are needed, and the module survives template updates.

        1. In the Administrator panel go to **Content → Site Modules** (**Extensions → Modules** on Joomla 3), click **New** and choose **Custom**.

        2. Set **Title** to `Rybbit`, **Show Title** to **Hide**, and **Position** to any position your template renders on every page. Templates rarely expose a `<head>` position; the loader below moves the script into the head from wherever the module is rendered.

        3. In the editor, use the **Toggle Editor** button (or **Code** view) so the script is not stripped, then paste:

           ```html
           <script>
           (function () {
             var s = document.createElement("script");
             s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
             s.defer = true;
             document.head.appendChild(s);
           })();
           </script>
           ```

        4. Set **Status** to **Published**, choose **On all pages** under **Menu Assignment**, and click **Save & Close**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Edit a child template (Joomla 4.1+) or your own copy of the template, otherwise the change is lost on the next template update.
        </Callout>

        1. Go to **System → Site Templates** and open your active template.

        2. Open `index.php` and add the snippet just before `</head>`:

           ```php
           <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
           </head>
           ```

        3. Click **Save & Close**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Module not on the page**: confirm it is published, assigned to **On all pages**, and that the chosen position exists in your template. Then clear the cache under **System → Clear Cache**.
* **TinyMCE strips the script**: open the **Editor - TinyMCE** plugin under **System → Plugins** (**Extensions → Plugins** on Joomla 3) and add `script[src|defer]` to **Extended Valid Elements**, or keep using the toggled-off editor when saving the module.
* **Page caching**: the **System - Page Cache** plugin serves cached HTML, so clear the cache after adding the snippet. The script itself loads client-side and works with cached pages.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Kajabi (/docs/guides/kajabi)





Kajabi has a site-wide **Header Page Scripts** field under **Site details** that puts code in the `<head>` of every page, but it deliberately skips Offer checkout and upsell pages. Those have their own **Checkout Tracking Code** setting, so a full install is two pastes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Kajabi [#add-the-snippet-to-kajabi]

    **Site-wide pages**

    1. From the **Dashboard**, open **Settings**.
    2. Under **Site settings**, click **Site details**.
    3. Scroll to **Page scripts** and paste the snippet into **Header Page Scripts**.
    4. Save.

    **Checkout and upsell pages**

    1. From the **Dashboard**, open **Settings**.
    2. Under **Payment settings**, click **Checkout**.
    3. In the **Checkout Tracking Code** section, click to edit the **Header tracking code** and paste the same snippet.
    4. Save.

    <Callout type="info">
      Do not paste the snippet into a page's **Custom Code** section (under **Customize > Settings**). That field is for CSS and JavaScript without `<style>` or `<script>` tags, and it only applies to that one page.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Checkout pages missing from the dashboard**: Header Page Scripts do not run on Offer checkout or upsell pages. Add the snippet under **Settings > Checkout > Checkout Tracking Code** as well.
* **Both fields filled, one visitor, two sites?** Use the same site ID in both places so a visitor who browses your site and then buys is one session, and funnels can follow them through checkout.
* **Snippet added to a page's Custom Code block instead**: the **Add block > Custom Code** block does accept `<script>` tags, but it only covers that page. Keep the site-wide field as the source of truth.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Kirby (/docs/guides/kirby)





Kirby templates are plain PHP files in `site/templates/`, and shared markup lives in `site/snippets/`. The snippet goes into whichever file owns your `<head>`: the Starterkit's `site/snippets/header.php`, or the template itself in a Plainkit project.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Kirby [#add-the-snippet-to-kirby]

    <Tabs items="[&#x22;Starterkit&#x22;, &#x22;Plainkit&#x22;]">
      <Tab>
        The Starterkit renders the document head from a shared snippet that every template includes with `<?php snippet('header') ?>`.

        1. Open `site/snippets/header.php`.
        2. Add the tag before `</head>`:

        ```php title="site/snippets/header.php"
        <head>
          <meta charset="utf-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title><?= $site->title() ?> | <?= $page->title() ?></title>
          <?= css(['assets/css/index.css', '@auto']) ?>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        3. Save. Every template that calls `snippet('header')` now loads the script.
      </Tab>

      <Tab>
        The Plainkit's `site/templates/default.php` contains only `<h1><?= $page->title() ?></h1>` and no document structure, so add the tag wherever you build your `<head>`. The usual pattern is a header snippet included by each template:

        ```php title="site/snippets/header.php"
        <!DOCTYPE html>
        <html lang="en">
        <head>
          <meta charset="utf-8">
          <title><?= $page->title() ?></title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        <body>
        ```

        ```php title="site/templates/default.php"
        <?php snippet('header') ?>
        <h1><?= $page->title() ?></h1>
        <?php snippet('footer') ?>
        ```
      </Tab>
    </Tabs>

    To keep the site ID out of the snippet, add it to `site/config/config.php` and read it with `<?= option('rybbit.siteId') ?>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Page cache**: if `cache.pages.active` is enabled in `site/config/config.php`, flush `site/cache/` after editing the snippet or cached pages keep the old head.
* **Multiple header snippets**: templates that include a different header (for example `snippet('header-landing')`) need the tag added there too.
* **Panel is not tracked**: `/panel` is a separate app that does not render your templates, so editing time never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Laravel (/docs/guides/laravel)





Laravel renders pages through Blade layouts, so the snippet goes into the layout file that wraps your site. Read the site ID from `config/services.php` and `.env` so it stays out of the template and differs per environment.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Laravel [#add-the-snippet-to-laravel]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to `.env`:

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then register them in `config/services.php`:

    ```php filename="config/services.php"
    <?php

    return [
        // ... other services

        'rybbit' => [
            'instance_url' => env('RYBBIT_INSTANCE_URL', 'https://app.rybbit.io'),
            'site_id' => env('RYBBIT_SITE_ID'),
        ],
    ];
    ```

    Run `php artisan config:clear` if your configuration is cached, otherwise the new keys are not picked up.

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open the Blade layout that wraps your pages. In a default install this is `resources/views/layouts/app.blade.php`; Breeze and Jetstream also ship `resources/views/layouts/guest.blade.php`, and Inertia apps use `resources/views/app.blade.php`. Add the tag inside `<head>`:

    ```php filename="resources/views/layouts/app.blade.php"
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>{{ config('app.name', 'Laravel') }}</title>
        @vite(['resources/css/app.css', 'resources/js/app.js'])

        @production
            <script src="{{ config('services.rybbit.instance_url') }}/api/script.js?siteId={{ config('services.rybbit.site_id') }}" defer></script>
        @endproduction
    </head>
    ```

    `@production` only renders the tag when `APP_ENV=production`, so local development is not tracked. Drop the directive if you also want data from staging.

    If you have several layouts (for example `app` and `guest`), add the tag to each one, or move it into a partial such as `resources/views/partials/rybbit.blade.php` and `@include` it from every layout.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in production**: run `php artisan config:clear` and `php artisan view:clear` after changing `.env` or `config/services.php`; cached config and compiled views keep the old values.
* **Tag missing locally**: `@production` hides it unless `APP_ENV=production`. Set that temporarily to test, or remove the directive.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Leadpages (/docs/guides/leadpages)





Every Leadpages page, site and pop-up has an **Analytics** tab in its builder settings with a **Head Section Tracking Code** field, and that is where the snippet goes. In the site builder the setting is site-wide, so one paste covers every page of the site; landing pages built on their own are tracked one page at a time.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Leadpages [#add-the-snippet-to-leadpages]

    1. Open the site or landing page in the builder.
    2. Click the **Settings** gear in the left-hand sidebar, then the **Analytics** tab.
    3. Paste the snippet into **Head Section Tracking Code**.
    4. Click **Save**, then **Update** to push the change to the published page.

    Repeat for each standalone landing page you want tracked. For sites, the code applies to every page in the site.

    Pop-ups have the same tracking code fields in their settings, but a pop-up shown on a page that already carries the snippet does not need its own copy.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: the page was saved but not updated. Click **Update** in the builder to republish.
* **Standalone pages missing**: tracking code on a site does not extend to landing pages published outside that site. Add the snippet to each one.
* **GA4 Measurement ID field**: the Analytics tab also has a field for a Google Analytics ID. That field is for GA4 only; the Rybbit snippet belongs in Head Section Tracking Code.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Lovable (/docs/guides/lovable)





Lovable has no project setting for custom head code, so the snippet goes into the app's HTML head like any other code change: ask Lovable to add it in chat, or open the **Code** tab and edit the file yourself. Either way, the live app only picks it up after you publish the change.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Lovable [#add-the-snippet-to-lovable]

    <Tabs items="[&#x22;Ask Lovable&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of the app on every page. Do not remove any existing head tags.
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Check the diff Lovable shows: the tag belongs in the document head, not in a React component.
      </Tab>

      <Tab>
        Open the **Code** tab in the project toolbar (editing needs a paid plan; on the Free plan the editor is read-only). Which file holds the head depends on when the project was created:

        * **Projects created from May 13, 2026** use TanStack Start. Add the script to the `head()` of the root route in `src/routes/__root.tsx`; the `<HeadContent />` component already in that file renders it into the `<head>`:

        ```tsx title="src/routes/__root.tsx"
        export const Route = createRootRoute({
          head: () => ({
            scripts: [
              { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: true },
            ],
          }),
          component: RootComponent,
        });
        ```

        * **Older React + Vite projects** have a single `index.html` at the project root. Paste the snippet before `</head>`:

        ```html title="index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Save with **Cmd+S** / **Ctrl+S**.
      </Tab>
    </Tabs>

    Then click **Publish** in the top right and choose **Publish changes**. Client-side route changes inside the app are tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live app still has no script**: Lovable does not push edits to the published app automatically. A dot on the **Publish** button means unpublished changes; open it and click **Publish changes**.
* **Free plan**: the Code tab is read-only, so use the chat prompt instead.
* **Script disappeared after a later prompt**: Lovable can rewrite the head when it regenerates the layout or upgrades the template. Add "keep the Rybbit script tag" to the project's Knowledge so future edits preserve it, and re-check the page source after big changes.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Magento (/docs/guides/magento)





Magento Open Source and Adobe Commerce have a **Scripts and Style Sheets** field in the design configuration that prints HTML into the `<head>` of every storefront page, so no theme edits are needed. On 2.4.7 and later the checkout page runs under a strict Content Security Policy, so the tracker's host also needs a CSP whitelist entry before it loads there.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Magento [#add-the-snippet-to-magento]

    1. In the Admin sidebar, go to **Content > Design > Configuration**.
    2. Find the row for the scope you want to track (usually the store view) and click **Edit** in the **Action** column.
    3. Expand **HTML Head**.
    4. Paste the snippet at the end of **Scripts and Style Sheets** and click **Save Configuration**.
    5. Go to **System > Cache Management** and refresh the invalidated cache types, then purge Varnish or your CDN if you use one.

    #### Allow the tracker under CSP (2.4.7 and later) [#allow-the-tracker-under-csp-247-and-later]

    Magento 2.4.7 switched the checkout page (`checkout_index_index`) to CSP restrict mode; other storefront pages stay in report-only mode. Scripts from hosts that are not whitelisted are blocked on checkout, so add the tracker's host to `script-src` and `connect-src` with a `csp_whitelist.xml` in a module of your own (plus the usual `registration.php` and `etc/module.xml`):

    ```xml title="app/code/Vendor/Rybbit/etc/csp_whitelist.xml"
    <?xml version="1.0"?>
    <csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
        <policies>
            <policy id="script-src">
                <values>
                    <value id="rybbit" type="host">https://app.rybbit.io</value>
                </values>
            </policy>
            <policy id="connect-src">
                <values>
                    <value id="rybbit" type="host">https://app.rybbit.io</value>
                </values>
            </policy>
        </policies>
    </csp_whitelist>
    ```

    Run `bin/magento setup:upgrade` and flush the cache after adding the module. If you self-host Rybbit, whitelist your own instance's domain instead.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

The order success page renders `Magento_Checkout::success.phtml` through the `checkout.success` block, which reserves an `order.success.additional.info` container for extra content. Add a block to that container from the same module as the CSP whitelist; the block reads the order from the checkout session.

```php title="app/code/Vendor/Rybbit/Block/Purchase.php"
<?php
namespace Vendor\Rybbit\Block;

class Purchase extends \Magento\Checkout\Block\Onepage\Success
{
    public function getOrder(): \Magento\Sales\Model\Order
    {
        return $this->_checkoutSession->getLastRealOrder();
    }
}
```

```xml title="app/code/Vendor/Rybbit/view/frontend/layout/checkout_onepage_success.xml"
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="order.success.additional.info">
            <block class="Vendor\Rybbit\Block\Purchase" name="rybbit.purchase" template="Vendor_Rybbit::purchase.phtml" cacheable="false"/>
        </referenceContainer>
    </body>
</page>
```

```php title="app/code/Vendor/Rybbit/view/frontend/templates/purchase.phtml"
<?php
/** @var \Vendor\Rybbit\Block\Purchase $block */
$order = $block->getOrder();
if (!$order->getId()) {
    return;
}
$items = [];
foreach ($order->getAllVisibleItems() as $item) {
    $items[] = [
        'item_id'   => $item->getSku(),
        'item_name' => $item->getName(),
        'price'     => (float) $item->getPrice(),
        'quantity'  => (int) $item->getQtyOrdered(),
    ];
}
$purchase = [
    'transaction_id' => $order->getIncrementId(),
    'value'          => (float) $order->getGrandTotal(),
    'currency'       => $order->getOrderCurrencyCode(),
    'items'          => $items,
];
?>
<script>
document.addEventListener('DOMContentLoaded', function () {
    window.rybbit.event('purchase', <?= /* @noEscape */ json_encode($purchase) ?>);
});
</script>
```

The script waits for `DOMContentLoaded` because the tracker loads with `defer`. Event properties are limited to 2048 characters of JSON, so drop `items` for stores with large orders. `getTaxAmount()` and `getShippingAmount()` are available on the same order object if you want those too.

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: design configuration is scoped, and a store-view row overrides the website and global rows. Edit the row that applies to the storefront you are checking, then flush the page cache and Varnish.
* **Tracked everywhere except checkout**: CSP restrict mode on `checkout_index_index` is blocking the script. Confirm the whitelist module is enabled and look for `Content-Security-Policy` errors naming `app.rybbit.io` in the browser console.
* **Purchase event missing**: `getLastRealOrder()` is only set in the session that placed the order, so reopening the success page later renders nothing.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Mintlify (/docs/guides/mintlify)





Mintlify includes every `.js` file in your docs content directory on every page, so the snippet goes into a small JavaScript file that injects the tag.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Mintlify [#add-the-snippet-to-mintlify]

    Create a JavaScript file in your content directory, next to `docs.json` and your `.mdx` pages:

    ```javascript filename="rybbit.js"
    (function () {
      var el = document.createElement("script");
      el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
      el.defer = true;
      document.head.appendChild(el);
    })();
    ```

    Commit and deploy. Mintlify picks the file up automatically; there is nothing to register in `docs.json`. See Mintlify's [custom scripts](https://www.mintlify.com/docs/customize/custom-scripts) page for the current rules on file placement.

    To pass [script attributes](/docs/script#script-attributes) such as skip patterns, set them on the element before appending it:

    ```javascript filename="rybbit.js"
    el.setAttribute("data-skip-patterns", JSON.stringify(["/internal/**"]));
    ```

    <Callout type="info">
      Mintlify sites are single-page apps. Rybbit records client-side navigation as pageviews, so no extra code is needed.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Mintlify pages are MDX, so you can attach handlers inline:

```mdx
<button
  onClick={() => window.rybbit?.event("download_clicked", { file: "getting-started.pdf" })}
>
  Download guide
</button>
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# MkDocs (/docs/guides/mkdocs)





MkDocs has an `extra_javascript` setting in `mkdocs.yml` that adds a script tag to every page, which works with any theme. If you run Material for MkDocs you can instead extend the theme and place the tag in `<head>` yourself.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to MkDocs [#add-the-snippet-to-mkdocs]

    <Tabs items="[&#x22;mkdocs.yml&#x22;, &#x22;Material theme override&#x22;]">
      <Tab value="mkdocs.yml">
        Add the script URL to `extra_javascript`. MkDocs 1.5 and later accept the mapping form with a `defer` key:

        ```yaml title="mkdocs.yml"
        extra_javascript:
          - path: https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
            defer: true
        ```

        On MkDocs 1.4 or older, list the plain URL instead:

        ```yaml title="mkdocs.yml"
        extra_javascript:
          - https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
        ```

        Themes render `extra_javascript` entries at the end of `<body>` rather than in `<head>`; the script still loads on every page.
      </Tab>

      <Tab value="Material theme override">
        1. Point Material at an overrides directory in `mkdocs.yml`:

           ```yaml title="mkdocs.yml"
           theme:
             name: material
             custom_dir: overrides
           ```

        2. Create `overrides/main.html` and fill the `extrahead` block, which Material reserves for custom tags inside `<head>`:

           ```html title="overrides/main.html"
           {% extends "base.html" %}

           {% block extrahead %}
             <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
           {% endblock %}
           ```
      </Tab>
    </Tabs>

    Rebuild with `mkdocs build` and deploy the `site/` directory (or `mkdocs gh-deploy`).

    If Material's `navigation.instant` feature is on, page changes go through the History API and Rybbit records them as pageviews without extra code.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Config error on `defer`**: the `path` / `defer` mapping needs MkDocs 1.5+. Run `mkdocs --version` and either upgrade or use the plain URL form.
* **`main.html` has no effect**: the override only applies when `theme.custom_dir` is set and the file sits at `overrides/main.html`, relative to `mkdocs.yml`.
* **Local previews are tracked**: `mkdocs serve` renders the same config as `mkdocs build`. Use a second Rybbit site for local work if that matters.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Moodle (/docs/guides/moodle)





Moodle has an **Additional HTML** admin setting that adds code to every page without touching the theme. Its **Within HEAD** field is where the snippet goes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Moodle [#add-the-snippet-to-moodle]

    1. Log in as an administrator and go to **Site administration → Appearance → Additional HTML**.
    2. Paste the snippet into **Within HEAD**.
    3. Click **Save changes**.

    The snippet now loads on every page, including course pages, activities and the login page. Users must be able to reach `app.rybbit.io` from their browser; nothing is proxied through the Moodle server.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Moodle renders standard HTML, so `data-rybbit-event` attributes work anywhere you control markup, for example in a course page's HTML block or a label:

```html
<a href="/course/view.php?id=42" data-rybbit-event="course_open" data-rybbit-prop-course="42">
  Open course
</a>
```

For enrolment or completion events, call `window.rybbit.event()` from a small block of JavaScript placed in the **When BODY is closed** field of the same Additional HTML page.

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the page source**: Moodle caches rendered output. Go to **Site administration → Development → Purge caches** and reload.
* **Pages inside the mobile app are not tracked**: the Moodle app renders course content in its own WebView with its own pages; the Additional HTML setting only affects the web site.
* **Snippet pasted into Custom CSS**: theme settings such as Boost's **Raw SCSS** only accept styles. Use Additional HTML for script tags.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Nextra (/docs/guides/nextra)





Nextra is a Next.js docs framework, so the snippet goes where it goes in any Next.js app: the root layout, rendered with `next/script`. Nextra 4 uses the App Router and `app/layout.jsx`; Nextra 3 uses the Pages Router and `pages/_app.jsx`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Nextra [#add-the-snippet-to-nextra]

    Use the `Script` component with `strategy="afterInteractive"` rather than a plain `<script>` tag; the `defer` attribute from the snippet is not needed.

    <Tabs items="[&#x22;Nextra 4 (App Router)&#x22;, &#x22;Nextra 3 (Pages Router)&#x22;]">
      <Tab value="Nextra 4 (App Router)">
        Add the `Script` next to the `Layout` in `app/layout.jsx` (or `.tsx`):

        ```jsx title="app/layout.jsx"
        import { Footer, Layout, Navbar } from "nextra-theme-docs";
        import { Head } from "nextra/components";
        import { getPageMap } from "nextra/page-map";
        import Script from "next/script";
        import "nextra-theme-docs/style.css";

        export default async function RootLayout({ children }) {
          return (
            <html lang="en" dir="ltr" suppressHydrationWarning>
              <Head />
              <body>
                <Layout
                  navbar={<Navbar logo={<b>My Docs</b>} />}
                  pageMap={await getPageMap()}
                  footer={<Footer>MIT {new Date().getFullYear()} © My Docs.</Footer>}
                >
                  {children}
                </Layout>
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```
      </Tab>

      <Tab value="Nextra 3 (Pages Router)">
        Create `pages/_app.jsx` if your project does not have one, and render the `Script` beside the page:

        ```jsx title="pages/_app.jsx"
        import Script from "next/script";

        export default function App({ Component, pageProps }) {
          return (
            <>
              <Component {...pageProps} />
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </>
          );
        }
        ```

        Do not put the tag in the `head` option of `theme.config.jsx`: that option renders through `next/head`, and Next.js warns against loading scripts there.
      </Tab>
    </Tabs>

    Nextra navigates between pages client-side. Rybbit records those route changes as pageviews, so no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Only the docs pages are tracked**: in Nextra 4 the tag belongs in the root `app/layout.jsx`, not in a nested `app/docs/layout.jsx`, otherwise landing pages outside `docs/` are missed.
* **Upgrading from Nextra 3**: Nextra 4 dropped the Pages Router and `theme.config`. Move the `Script` from `pages/_app.jsx` to `app/layout.jsx` as part of the migration.
* **Proxying through your own domain**: see the [Next.js guide](/docs/guides/react/next-js) for rewrites; every endpoint must be rewritten, not just `script.js`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Odoo (/docs/guides/odoo)





The Odoo Website app has a **Code Injection** setting in the website editor's theme panel with separate `<head>` and `</body>` fields that apply to every page of the website. The snippet goes in the `<head>` field. This works on Odoo Online, Odoo.sh and on-premise installs of Odoo 17 and 18.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Odoo [#add-the-snippet-to-odoo]

    1. Open your website's frontend and click **Edit** in the top bar.
    2. Switch to the **Theme** tab of the editor panel.
    3. Scroll to the **Advanced** section and, next to **Code Injection*&#x2A;, click &#x2A;*`<head>`**.
    4. Paste the snippet into the editor that opens and click **Save**.
    5. Click **Save** in the website editor to publish the change.

    The code is stored per website. If you run several websites from one Odoo database, switch website in the top bar and repeat the steps for each one.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Odoo eCommerce pages render standard HTML, so use `data-rybbit-event` attributes on any element you add in the editor, or call `window.rybbit.event()` from the `</body>` Code Injection field:

```html
<script>
  document.addEventListener("click", function (e) {
    if (e.target.closest("#add_to_cart")) {
      window.rybbit.event("add_to_cart");
    }
  });
</script>
```

The confirmation page is served at `/shop/confirmation`; a script that checks `window.location.pathname` there can send a `purchase` event once per order.

## Troubleshooting [#troubleshooting]

* **The `<head>` button is missing**: Code Injection requires the **Website → Editor and Designer** access right. An administrator can grant it under **Settings → Users & Companies → Users**, on the user's **Access Rights** tab.
* **Change is visible while logged in but not for visitors**: click **Save** in the editor after closing the code window; the code is published with the page.
* **Multiple websites**: the field applies only to the website currently selected in the editor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Payload (/docs/guides/payload)





Payload is a headless CMS that installs into a Next.js app: the admin panel lives in the `(payload)` route group and your site in the `(frontend)` route group. The tracking snippet goes into the frontend root layout, not into Payload's config or admin panel.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Payload [#add-the-snippet-to-payload]

    <Callout type="info">
      Payload has no template or head setting to paste into. Add the snippet to the root layout of the Next.js frontend that renders your site.
    </Callout>

    In both the `website` and `blank` templates created by `npx create-payload-app`, the frontend root layout is `src/app/(frontend)/layout.tsx`. Render `next/script` there, exactly as in the [Next.js guide](/docs/guides/react/next-js), so the script loads on every public route and stays out of the admin panel under `src/app/(payload)/`.

    ```tsx title="src/app/(frontend)/layout.tsx"
    import Script from "next/script";

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            {children}
            <Script
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    The script tracks client-side route changes automatically, so Next.js `<Link>` navigation between Payload pages and posts is counted without extra code.

    If your frontend is a separate app (Nuxt, Astro, SvelteKit) that fetches from Payload's REST or GraphQL API, follow that framework's guide instead: [Nuxt](/docs/guides/vue/nuxt), [Astro](/docs/guides/astro), [SvelteKit](/docs/guides/svelte/sveltekit), [Remix](/docs/guides/react/remix).
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live Preview counts as visits**: the admin panel's Live Preview loads your frontend in an iframe at the URL set in `admin.livePreview.url`. Editors' preview sessions are tracked like any other visitor. Point `livePreview.url` at a separate preview deployment registered as its own site in Rybbit, or skip the tag in preview builds.
* **Draft preview routes**: if you use the `website` template's `/next/preview` route or Next.js draft mode, those pages are also tracked. Add `data-skip-patterns='["/next/**"]'` to the script tag to exclude them.
* **Admin panel is not tracked**: `/admin` is rendered by the `(payload)` route group, which has its own layout without the snippet. Put the tag in the `(frontend)` layout only.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Phoenix (/docs/guides/phoenix)





Phoenix renders every page inside the root layout, `lib/my_app_web/components/layouts/root.html.heex`, which owns the `<html>` and `<head>` tags, so the snippet goes there. Read the site ID from application config set in `config/runtime.exs`, so it comes from an environment variable at boot and stays out of the template.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Phoenix [#add-the-snippet-to-phoenix]

    #### Configure the site ID [#configure-the-site-id]

    `config/runtime.exs` runs when the app boots, including inside a release, so it is the right place to read environment variables. Add a `:rybbit` key for your app (replace `:my_app` with your OTP app name):

    ```elixir filename="config/runtime.exs"
    config :my_app, :rybbit,
      instance_url: System.get_env("RYBBIT_INSTANCE_URL", "https://app.rybbit.io"),
      site_id: System.get_env("RYBBIT_SITE_ID")
    ```

    Then set the variables where the app runs:

    ```bash
    export RYBBIT_INSTANCE_URL=https://app.rybbit.io
    export RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    #### Expose the config to the layout [#expose-the-config-to-the-layout]

    Templates in `lib/my_app_web/components/layouts/` are embedded into the `MyAppWeb.Layouts` module, so a function defined there is callable from `root.html.heex`. Add one that returns the config:

    ```elixir filename="lib/my_app_web/components/layouts.ex"
    defmodule MyAppWeb.Layouts do
      use MyAppWeb, :html

      embed_templates "layouts/*"

      def rybbit_config, do: Application.get_env(:my_app, :rybbit, [])
    end
    ```

    #### Add the tag to the root layout [#add-the-tag-to-the-root-layout]

    Open `lib/my_app_web/components/layouts/root.html.heex` and add the tag inside `<head>`, after the existing `app.css` and `app.js` tags:

    ```html filename="lib/my_app_web/components/layouts/root.html.heex"
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta name="csrf-token" content={get_csrf_token()} />
      <.live_title suffix=" · Phoenix Framework">{assigns[:page_title] || "MyApp"}</.live_title>
      <link phx-track-static rel="stylesheet" href={~p"/assets/app.css"} />
      <script defer phx-track-static type="text/javascript" src={~p"/assets/app.js"}></script>

      <script
        :if={rybbit_config()[:site_id]}
        src={"#{rybbit_config()[:instance_url]}/api/script.js?siteId=#{rybbit_config()[:site_id]}"}
        defer
      ></script>
    </head>
    ```

    The `:if` attribute skips the tag when `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.

    #### LiveView navigation [#liveview-navigation]

    `<.link navigate>`, `<.link patch>`, `push_navigate/2` and `push_patch/2` change the URL with `history.pushState` (or `replaceState` when `replace: true`) and keep the root layout, including its `<head>`, in place. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each live navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `phx:` event listener is needed. A regular `<.link href>` does a full page load, which the script also tracks.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `config/runtime.exs` is evaluated at boot, so restart the app or release after changing `RYBBIT_SITE_ID`. Check with `Application.get_env(:my_app, :rybbit)` in `iex -S mix`.
* **Content Security Policy**: if you set a `content-security-policy` header in a plug, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Podia (/docs/guides/podia)





Podia has a **Third-party code** setting under **Settings > Analytics** that adds the snippet to every public page of your site, including checkout. Podia inserts custom code just before the closing `</body>` tag rather than in `<head>`; the Rybbit script loads with `defer` and works the same from either position.

<Callout type="warn">
  Third-party code is available on Podia's **Mover** and **Shaker** plans. On the free plan the Third-party code option is not shown.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Podia [#add-the-snippet-to-podia]

    1. From your home feed, click your site name and choose **Admin**.
    2. In the Admin sidebar, open **Settings > Analytics**.
    3. Click **Edit** next to **Third-party code**.
    4. Paste the snippet into the **Website tracking code** field.
    5. Click **Save**. The code is live as soon as it is saved; there is no separate publish step.

    The website tracking code runs on every public page of your site and on checkout pages. It does not run inside logged-in areas such as the customer dashboard, product viewer or community spaces.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Podia has a second field, **Conversion tracking code**, directly below the website tracking code. Code in that field runs only on the thank-you page after a purchase or membership signup, and Podia exposes the order as a `Podia.Conversion` object on that page (once per order; it is gone after a refresh).

Paste this into **Conversion tracking code** to send a `purchase` event with the order details:

```html
<script>
(function () {
  var c = window.Podia && window.Podia.Conversion;
  if (!c) return;
  var payload = {
    product: c.object.name,
    order_id: c.object.order_id,
    value: c.revenue,
    currency: c.currency
  };
  var start = Date.now();
  (function send() {
    if (window.rybbit && typeof window.rybbit.event === "function") {
      return window.rybbit.event("purchase", payload);
    }
    if (Date.now() - start < 8000) setTimeout(send, 150);
  })();
})();
</script>
```

The short polling loop is there because Podia runs the conversion code before the deferred tracking script has finished loading. `revenue` is `0` for free products and free membership plans, so filter on `value` in the dashboard if you only want paid orders.

## Troubleshooting [#troubleshooting]

* **No Third-party code option**: the site is on the free plan. Third-party code requires Mover or Shaker.
* **No pageviews while you test**: Podia does not output tracking code when you are logged in to your own Podia account. Test in a private window, or log out first.
* **Logged-in member pages are missing**: expected. Custom code runs only on public pages and checkout, not in the customer dashboard, product viewer or community.
* **Duplicate purchase events**: `Podia.Conversion` is only present on the first load of the thank-you page, so a refresh does not resend. If you see duplicates, make sure the event script is in Conversion tracking code only and not also in Website tracking code.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Preact (/docs/guides/preact)





A Preact app scaffolded with `npm init preact` (or Vite's `preact` template) has a single `index.html` at the project root. Paste the snippet into its `<head>` and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Preact [#add-the-snippet-to-preact]

    Open `index.html` at the root of the project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Vite + Preact</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/index.jsx"></script>
      </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Route changes made by `preact-iso`, `preact-router` or a similar router are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw.

```jsx title="src/components/SignupButton.jsx"
export function SignupButton() {
  const handleClick = () => {
    if (window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# PrestaShop (/docs/guides/prestashop)





PrestaShop's back office has no built-in setting for custom `<head>` code, so the snippet goes in either through a header-injection module from the Addons marketplace or directly into your theme's `head.tpl`. Either way, clear the cache afterwards.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to PrestaShop [#add-the-snippet-to-prestashop]

    <Tabs items="[&#x22;Custom code module&#x22;, &#x22;Theme files&#x22;]">
      <Tab>
        1. In the back office, go to **Modules > Module Manager** (or **Module Catalog**) and install a module that injects custom HTML into the page header, for example a "Custom HTML" or "Header code" module from the [PrestaShop Addons marketplace](https://addons.prestashop.com/).
        2. Open the module's configuration, paste the snippet into its head / header code field, and save.
        3. Go to **Advanced Parameters > Performance** and click **Clear cache**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Edit a child theme. Changes to the parent theme are lost on theme updates.
        </Callout>

        1. Over FTP/SFTP or a file manager, open `/themes/your-theme-name/templates/_partials/head.tpl`.
        2. Paste the snippet at the end of the file, before the closing `</head>` tag, and save.
        3. Go to **Advanced Parameters > Performance** and click **Clear cache**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Add this to your theme's `order-confirmation.tpl`, or output it from a module hooked to the order confirmation page. PrestaShop renders templates with Smarty, so the `$order` variables are filled in with the order data:

```html
{if isset($order)}
<script>
(function () {
  function waitForRybbit(callback, timeout) {
    var start = Date.now();
    (function check() {
      if (window.rybbit && typeof window.rybbit.event === 'function') {
        callback();
      } else if (Date.now() - start < timeout) {
        setTimeout(check, 100);
      }
    })();
  }

  waitForRybbit(function () {
    window.rybbit.event('purchase', {
      transaction_id: '{$order.details.reference}',
      value: {$order.totals.total.amount},
      currency: '{$order.totals.total.currency}'
    });
  }, 5000);
})();
</script>
{/if}
```

`waitForRybbit` polls until the tracking script from `head.tpl` has defined `window.rybbit`, so the event is not lost when the confirmation script runs first.

## Troubleshooting [#troubleshooting]

* **Script not on the page**: clear the cache under **Advanced Parameters > Performance**, and temporarily disable any JavaScript optimisation or combine/minify module.
* **Theme updates overwrite the snippet**: keep template edits in a child theme; parent-theme changes are lost on update.
* **Purchase event missing**: the `$order` Smarty variables differ between PrestaShop versions. Compare them with your version's `order-confirmation.tpl` and place a test order to confirm the event arrives.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Qwik (/docs/guides/qwik)





A Qwik City app renders the whole document from `src/root.tsx`, which owns the `<head>` and `<body>` elements. Add the snippet to that `<head>` and it is on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Qwik [#add-the-snippet-to-qwik]

    Open `src/root.tsx` and add the tag inside `<head>`, after `<RouterHead />`:

    ```tsx title="src/root.tsx"
    import { component$ } from "@builder.io/qwik";
    import { QwikCityProvider, RouterOutlet } from "@builder.io/qwik-city";
    import { RouterHead } from "./components/router-head/router-head";

    import "./global.css";

    export default component$(() => {
      return (
        <QwikCityProvider>
          <head>
            <meta charset="utf-8" />
            <RouterHead />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body lang="en">
            <RouterOutlet />
          </body>
        </QwikCityProvider>
      );
    });
    ```

    `src/components/router-head/router-head.tsx` renders per-route `head` exports (title, meta, links). Keep the Rybbit tag in `root.tsx` so it does not depend on any route's `head` export.

    Navigations through Qwik City's `<Link>` component are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a `$` event handler. Handlers only run in the browser, so `window` is always defined; guard against a blocked or still-loading script.

```tsx title="src/components/signup-button.tsx"
import { component$ } from "@builder.io/qwik";

export const SignupButton = component$(() => {
  return (
    <button
      onClick$={() => {
        if (window.rybbit) {
          window.rybbit.event("signup_click", { location: "hero" });
        }
      }}
    >
      Sign up
    </button>
  );
});
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ruby on Rails (/docs/guides/rails)





Rails wraps every page in `app/views/layouts/application.html.erb`, so the snippet goes into that layout's `<head>`. Read the site ID from a custom `config.x` setting fed by an environment variable, so the template stays free of hard-coded IDs and each environment can use its own site.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ruby on Rails [#add-the-snippet-to-ruby-on-rails]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to your environment (`.env` if you use dotenv-rails, otherwise your host's environment settings):

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then expose them through the `config.x` namespace in `config/application.rb`:

    ```ruby filename="config/application.rb"
    module MyApp
      class Application < Rails::Application
        # ... existing configuration

        config.x.rybbit.instance_url = ENV.fetch("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
        config.x.rybbit.site_id = ENV["RYBBIT_SITE_ID"]
      end
    end
    ```

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open `app/views/layouts/application.html.erb` and add the tag inside `<head>`, after the stylesheet and JavaScript tags:

    ```erb filename="app/views/layouts/application.html.erb"
    <head>
      <title><%= content_for(:title) || "MyApp" %></title>
      <meta name="viewport" content="width=device-width,initial-scale=1">
      <%= csrf_meta_tags %>
      <%= csp_meta_tag %>
      <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
      <%= javascript_importmap_tags %>

      <% if Rails.configuration.x.rybbit.site_id.present? %>
        <script src="<%= Rails.configuration.x.rybbit.instance_url %>/api/script.js?siteId=<%= Rails.configuration.x.rybbit.site_id %>" defer></script>
      <% end %>
    </head>
    ```

    The `if` guard skips the tag wherever `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.

    If you have more than one HTML layout (for example `application.html.erb` and `admin.html.erb`), add the tag to each, or move it into a partial such as `app/views/layouts/_rybbit.html.erb` and `<%= render "layouts/rybbit" %>` from every layout. Mailer layouts do not need it.

    #### Turbo and Hotwire [#turbo-and-hotwire]

    Turbo Drive replaces the page `<body>` on each visit, merges the `<head>`, and pushes the new URL with `history.pushState`. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so every Turbo visit is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `turbo:load` listener is needed. Because the script tag is in `<head>` and identical on every page, Turbo Drive keeps the existing tag instead of loading it again.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `config/application.rb` is read once at boot, so restart the server after changing `RYBBIT_SITE_ID`. Check `Rails.configuration.x.rybbit.site_id` in `rails console` if the tag does not render.
* **Content Security Policy**: if you set a policy in `config/initializers/content_security_policy.rb`, add your Rybbit host to `script_src` and `connect_src`, or the browser blocks both the script and the `/api/track` requests. Alternatively [proxy the script](/docs/proxy-guide) through your own domain so no extra origin is needed.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Replit (/docs/guides/replit)





Replit has no publishing setting for custom head code, so the snippet goes into the app's HTML entry file: ask Agent to add it, or open the file in the workspace and paste it yourself. The change reaches the live URL only after you republish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Replit [#add-the-snippet-to-replit]

    <Tabs items="[&#x22;Ask Agent&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the Agent chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of the app's HTML entry file so it loads on every page. Keep all existing head tags.
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Review the change before you approve it: the tag belongs in the HTML document, not in a React component or server file.
      </Tab>

      <Tab>
        Open the file that owns the `<head>` from the **Files** pane of the workspace:

        * Agent-built web apps are typically a Vite + React client with an Express server, and the HTML entry is `client/index.html`. Some projects keep it at `index.html` in the project root.
        * Next.js projects use `app/layout.tsx` with `next/script`, as in the [Next.js guide](/docs/guides/react/next-js).
        * Plain HTML projects (Static deployments): add the tag to every page, or to the shared template if you have one.

        Paste the snippet before `</head>`:

        ```html title="client/index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```
      </Tab>
    </Tabs>

    Then click **Publish** in the upper right (or **Republish** for an app that is already live) so a new release goes out at the same URL. In-app route changes are tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live app has no script**: changes in the Project Editor do not replace the live release on their own. Test in Preview, then click **Republish**.
* **Agent rewrote the file**: a later request can regenerate `client/index.html`. Tell Agent to keep the Rybbit script when you ask for layout changes, and re-check the page source after large refactors.
* **Numbers differ from Replit's deployment analytics**: Replit counts requests at the server; Rybbit counts browser pageviews after ad blockers and bot filtering, so the two rarely match exactly.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Sanity (/docs/guides/sanity)





Sanity is a headless CMS: your frontend queries content from the Content Lake and Sanity Studio is only the editing app. The tracking snippet therefore goes into the frontend that renders your site, not into Sanity.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Sanity [#add-the-snippet-to-sanity]

    <Callout type="info">
      Sanity has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Sanity.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Sanity frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby)
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Embedded Studio pageviews**: if Sanity Studio is mounted inside your frontend (for example at `/studio` in a Next.js app), the snippet in your root layout also runs there. Add `data-skip-patterns='["/studio/**"]'` to the script tag so editor sessions are not counted as visits.
* **Hosted Studio is not tracked**: a Studio deployed to `*.sanity.studio` is a separate app without the snippet, so time spent editing never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Shopify Hydrogen (/docs/guides/shopify-hydrogen)





Hydrogen storefronts render the HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file's `Layout` component, and the tracker's host is added to the Content Security Policy that `app/entry.server.tsx` builds. This guide is for headless Hydrogen storefronts; for an Online Store theme, see the [Shopify guide](/docs/guides/shopify).

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Shopify Hydrogen [#add-the-snippet-to-shopify-hydrogen]

    Hydrogen ships with a nonce-based CSP, so a plain `<script>` tag without the nonce is blocked. Use Hydrogen's `Script` component, which adds the nonce for you.

    1. Open `app/root.tsx` and add the tag inside `<head>` of the `Layout` component:

    ```tsx title="app/root.tsx"
    import { Analytics, getShopAnalytics, Script, useNonce } from "@shopify/hydrogen";

    export function Layout({children}: {children?: React.ReactNode}) {
      const nonce = useNonce();

      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width,initial-scale=1" />
            <Meta />
            <Links />
            <Script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer />
          </head>
          <body>
            {children}
            <ScrollRestoration nonce={nonce} />
            <Scripts nonce={nonce} />
          </body>
        </html>
      );
    }
    ```

    2. Open `app/entry.server.tsx` and allow the tracker's host in the CSP. Values you pass for `connectSrc` are merged with Hydrogen's defaults, but `scriptSrc` has no default to merge with (it falls back to `default-src`), so list Shopify's CDN alongside Rybbit:

    ```tsx title="app/entry.server.tsx"
    const {nonce, header, NonceProvider} = createContentSecurityPolicy({
      shop: {
        checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
        storeDomain: context.env.PUBLIC_STORE_DOMAIN,
      },
      scriptSrc: ["'self'", "https://cdn.shopify.com", "https://app.rybbit.io"],
      connectSrc: ["https://app.rybbit.io"],
    });
    ```

    `connect-src` lets the tracker post events; `script-src` is needed because features such as session replay load a second script from the same host at runtime. If you self-host Rybbit, use your instance's domain.

    Restart the dev server. Client-side navigation between routes is tracked automatically as pageviews. Projects created before Hydrogen moved to React Router import `Meta`, `Links` and `Scripts` from `@remix-run/react`; the edit is the same.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Hydrogen's `Analytics.Provider` already publishes storefront events (`product_viewed`, `product_added_to_cart`, `cart_updated` and others), so subscribe to them once in a small component instead of instrumenting each route.

```tsx title="app/components/RybbitAnalytics.tsx"
import { useAnalytics } from "@shopify/hydrogen";
import { useEffect } from "react";

export function RybbitAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register("Rybbit");

  useEffect(() => {
    subscribe("product_viewed", (data) => {
      const product = data.products[0];
      if (!product) return;
      window.rybbit?.event("view_item", {
        item_id: product.sku || product.variantId,
        item_name: product.title,
        item_variant: product.variantTitle,
        price: Number(product.price),
      });
    });
    subscribe("product_added_to_cart", (data) => {
      const line = data.currentLine;
      if (!line) return;
      window.rybbit?.event("add_to_cart", {
        item_id: line.merchandise.sku || line.merchandise.id,
        item_name: line.merchandise.product.title,
        price: Number(line.cost.totalAmount.amount),
        currency: line.cost.totalAmount.currencyCode,
        quantity: line.quantity,
      });
    });
    ready();
  }, []);

  return null;
}
```

Render `<RybbitAnalytics />` inside `<Analytics.Provider>` in the `App` component of `app/root.tsx`. Declare `window.rybbit` with the type from [Track events](/docs/track-events#typescript-support) so TypeScript accepts the calls. Skip `page_viewed`: the tracker records route changes itself.

<Callout type="info">
  Checkout does not run in Hydrogen. Track purchases with the custom web pixel from the [Shopify guide](/docs/guides/shopify#purchase), which works for Hydrogen and Online Store checkouts alike.
</Callout>

## Troubleshooting [#troubleshooting]

* **`Refused to load the script` in the console**: the CSP change in `entry.server.tsx` is missing or the dev server was not restarted. The nonce alone is not enough once session replay loads its second script.
* **`POST /api/track` blocked**: `connectSrc` does not include the tracker's host. Self-hosted instances need their own domain here.
* **Early events dropped**: on a cold load a subscription can fire before the deferred script runs. The optional chaining above skips those; wrap the calls in `window.rybbit.onReady()` if you need every one.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Shopify (/docs/guides/shopify)





On Shopify the snippet goes into your theme's `theme.liquid` layout, which wraps every storefront page. Checkout runs on Shopify's own sandboxed pages, so purchases are tracked separately through a custom web pixel.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Shopify [#add-the-snippet-to-shopify]

    1. In Shopify admin, go to **Online Store > Themes**.
    2. On your current theme, click the &#x2A;*...** button next to **Customize** and choose **Edit code**.
    3. Open `theme.liquid` in the **Layout** folder.
    4. Paste the snippet just before the closing `</head>` tag and click **Save**.

    Theme updates can overwrite `theme.liquid`. Shopify has no child-theme system, so after updating a purchased theme, re-add the snippet.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Storefront templates can call `window.rybbit.event()` directly. Wrap the calls in a `DOMContentLoaded` listener because the tracking script is loaded with `defer`, and divide Liquid prices by 100 because they are in cents.

<Callout type="warn">
  Back up your theme before editing code. Liquid object names such as `product.selected_or_first_available_variant` and the form selectors below vary between themes, so adjust them to match yours.
</Callout>

#### View product [#view-product]

Add to your main product template (`sections/main-product.liquid` or `templates/product.liquid`, depending on the theme):

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var variant = {{ product.selected_or_first_available_variant | json }};
  window.rybbit.event('view_item', {
    item_id: variant.sku || variant.id,
    item_name: {{ product.title | json }},
    item_variant: variant.title === 'Default Title' ? null : variant.title,
    price: variant.price / 100,
    currency: {{ cart.currency.iso_code | json }}
  });
});
</script>
```

#### Add to cart [#add-to-cart]

In the same template, listen on the product form. Themes with an AJAX cart drawer usually fire their own JavaScript event after an item is added; hooking that is more reliable than the form submit.

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var form = document.querySelector('form[action="/cart/add"]');
  if (!form) return;
  form.addEventListener('submit', function () {
    var variant = {{ product.selected_or_first_available_variant | json }};
    var qty = form.querySelector('[name="quantity"]');
    window.rybbit.event('add_to_cart', {
      item_id: variant.sku || variant.id,
      item_name: {{ product.title | json }},
      price: variant.price / 100,
      currency: {{ cart.currency.iso_code | json }},
      quantity: qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1
    });
  });
});
</script>
```

#### Begin checkout [#begin-checkout]

Add to your cart template (`sections/main-cart-items.liquid` or `templates/cart.liquid`) to track clicks on the checkout button:

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var button = document.querySelector('[name="checkout"]');
  if (!button) return;
  button.addEventListener('click', function () {
    var cart = {{ cart | json }};
    window.rybbit.event('begin_checkout', {
      currency: cart.currency,
      value: cart.total_price / 100,
      items: cart.items.map(function (item) {
        return { item_id: item.sku || item.variant_id, quantity: item.quantity, price: item.final_price / 100 };
      })
    });
  });
});
</script>
```

Event properties are limited to 2048 characters of serialised JSON and larger payloads are rejected, not truncated. Keep `items` compact, or send only the totals for large carts.

#### Purchase [#purchase]

Checkout and the order status page do not load your theme, and the old **Order status page > Additional scripts** field is deprecated: view-only since August 28, 2025, with non-Plus stores required to migrate by August 26, 2026. Track purchases with a custom web pixel from [Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations) instead.

Pixels run in a sandbox with no access to `window.rybbit`, so the pixel posts the event straight to Rybbit's track endpoint.

1. In Shopify admin, go to **Settings > Customer events**.
2. Click **Add custom pixel**, name it `Rybbit`, and click **Add pixel**.
3. Paste the code below, replace `YOUR_SITE_ID`, then **Save** and **Connect** the pixel.

```javascript
analytics.subscribe("checkout_completed", (event) => {
  const checkout = event.data.checkout;
  const items = (checkout.lineItems || []).map((li) => ({
    id: li.variant?.sku || li.variant?.id,
    qty: li.quantity,
    price: li.variant?.price?.amount,
  }));

  fetch("https://app.rybbit.io/api/track", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    keepalive: true,
    body: JSON.stringify({
      type: "custom_event",
      site_id: "YOUR_SITE_ID",
      event_name: "purchase",
      // properties must be a JSON string of at most 2048 characters
      properties: JSON.stringify({
        transaction_id: checkout.order?.id || checkout.token,
        value: checkout.totalPrice?.amount,
        currency: checkout.currencyCode,
        items,
      }),
    }),
  });
});
```

`checkout_completed` fires once per placed order. The same [Customer Events](https://shopify.dev/docs/api/customer-events) API also exposes `product_added_to_cart` and `checkout_started`, so you can move add-to-cart and begin-checkout into the pixel too if theme code is unreliable on your store.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# SolidJS (/docs/guides/solid)





A client-side Solid app built with Vite has a single `index.html` at the project root; a SolidStart app renders its document from `src/entry-server.tsx`. Paste the snippet into the `<head>` of whichever file your project has and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to SolidJS [#add-the-snippet-to-solidjs]

    <Tabs items="[&#x22;Vite&#x22;, &#x22;SolidStart&#x22;]">
      <Tab value="Vite">
        Open `index.html` at the root of the project (the file `npm create solid@latest` generates for the vanilla templates) and paste the snippet inside `<head>`:

        ```html title="index.html"
        <!DOCTYPE html>
        <html lang="en">
          <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <title>Solid App</title>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            <div id="root"></div>
            <script src="/src/index.tsx" type="module"></script>
          </body>
        </html>
        ```
      </Tab>

      <Tab value="SolidStart">
        SolidStart has no `index.html`. The `<html>` document is the `document` prop of `<StartServer>` in `src/entry-server.tsx`; `src/app.tsx` only renders the router inside it. Add the tag to `<head>` next to `{assets}`:

        ```tsx title="src/entry-server.tsx"
        // @refresh reload
        import { createHandler, StartServer } from "@solidjs/start/server";

        export default createHandler(() => (
          <StartServer
            document={({ assets, children, scripts }) => (
              <html lang="en">
                <head>
                  <meta charset="utf-8" />
                  <meta name="viewport" content="width=device-width, initial-scale=1" />
                  <link rel="icon" href="/favicon.ico" />
                  <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
                  {assets}
                </head>
                <body>
                  <div id="app">{children}</div>
                  {scripts}
                </body>
              </html>
            )}
          />
        ));
        ```

        Restart the dev server after the change.
      </Tab>
    </Tabs>

    Route changes made by `@solidjs/router` (including SolidStart's file routes) are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw; in SolidStart the guard also covers server rendering.

```tsx title="src/components/SignupButton.tsx"
export default function SignupButton() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Squarespace (/docs/guides/squarespace)





Squarespace injects custom HTML into every page through its **Code Injection** panel, so no template edits are needed.

<Callout type="warn">
  Code Injection is available on the **Business** and **Commerce** plans. It is not available on the Personal plan.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Squarespace [#add-the-snippet-to-squarespace]

    1. From the Home Menu, open **Settings**.
    2. Open **Website**, then **Code Injection** (listed under **Advanced** or **Developer** depending on your Squarespace version).
    3. Paste the snippet into the **Header** field. The script is deferred, so it does not delay page rendering.
    4. Click **Save** at the top of the panel.

    The **Footer** field also works and loads the script on every page. Leave the **Lock Page** and **Order Confirmation Page** fields alone; they only apply to those single pages.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Code Injection is missing from Settings**: the site is on the Personal plan. Upgrade to Business or Commerce.
* **Only the checkout is tracked**: the snippet was pasted into **Order Confirmation Page** instead of **Header** or **Footer**.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Starlight (/docs/guides/starlight)





Starlight, the documentation theme for Astro, has a `head` option in its integration config that adds tags to every page. The snippet goes there, in `astro.config.mjs`, so no component overrides are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Starlight [#add-the-snippet-to-starlight]

    Open `astro.config.mjs` at the root of your project and add a `script` entry to the `head` array of the `starlight()` integration:

    ```javascript title="astro.config.mjs"
    import { defineConfig } from "astro/config";
    import starlight from "@astrojs/starlight";

    export default defineConfig({
      integrations: [
        starlight({
          title: "My Docs",
          head: [
            {
              tag: "script",
              attrs: {
                src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                defer: true,
              },
            },
          ],
        }),
      ],
    });
    ```

    Each `head` entry becomes an HTML element with the given attributes; `defer: true` renders as a boolean attribute. Rebuild with `npm run build` and deploy the `dist/` directory.

    <Callout type="info">
      Entries in `head` are written to the page as-is and skip Astro's script bundling, which is what you want for a remote tracker. Only override the `Head` component if you need to import a local asset.
    </Callout>

    Starlight serves each page as a full document, so every navigation is a normal pageview and no route-change handling is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Local previews are tracked**: `head` applies to `astro dev` as well as `astro build`. Read the site ID from an environment variable that only your deploy sets (`process.env.RYBBIT_SITE_ID`) and push the entry only when it is present, or keep a separate site in Rybbit for development.
* **Tag missing after editing the config**: the dev server restarts itself when `astro.config.mjs` changes, but a deployed site needs a fresh build.
* **Head component override**: if your project already overrides Starlight's `Head` component, make sure it still renders the default head (the override docs show how), otherwise config `head` entries are dropped with it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Statamic (/docs/guides/statamic)





Statamic wraps every template in a layout, and a fresh install uses `resources/views/layout.antlers.html` by default. The snippet goes in that layout's `<head>`, so it loads on every page without touching individual templates.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Statamic [#add-the-snippet-to-statamic]

    1. Open `resources/views/layout.antlers.html`.
    2. Add the tag before `</head>`:

    ```html title="resources/views/layout.antlers.html"
    <!doctype html>
    <html lang="{{ site:short_locale }}">
    <head>
        <meta charset="utf-8">
        <title>{{ title }} | {{ site:name }}</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        {{ template_content }}
    </body>
    </html>
    ```

    3. Save. Templates rendered through this layout (`{{ template_content }}`) now include the script.

    If an entry or collection sets a different `layout` field, add the tag to that layout file too, or move it into a partial such as `resources/views/partials/rybbit.antlers.html` and `{{ partial:rybbit }}` it from each layout. If your views use Blade (`layout.blade.php`), the same tag goes in the same place.

    To keep the site ID out of version control, put it in `.env` as `RYBBIT_SITE_ID` and use `{{ config:services:rybbit:site_id }}` after adding a `rybbit` entry to `config/services.php`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Static caching**: with `half` or `full` static caching enabled in `config/statamic/static_caching.php`, run `php please static:clear` after editing the layout, otherwise cached pages keep the old head.
* **Live Preview counts as visits**: the control panel's Live Preview renders your entry in an iframe at its real URL with a `token` query parameter. Editors' previews are tracked like any other visit, so check analytics from the live site rather than the control panel.
* **Control panel is not tracked**: `/cp` uses Statamic's own views, so the snippet never runs there.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Storyblok (/docs/guides/storyblok)





Storyblok is a headless CMS: it stores content and delivers it through its APIs, while your frontend renders the pages. The tracking snippet therefore goes into the frontend's root layout, not into Storyblok.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Storyblok [#add-the-snippet-to-storyblok]

    <Callout type="info">
      Storyblok has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Storyblok.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Remix](/docs/guides/react/remix)
        * [Gatsby](/docs/guides/react/gatsby)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>

    The script tracks client-side route changes automatically, so navigation between stories in any of these frameworks is counted without extra code.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Visual Editor previews count as visits**: the Visual Editor loads your frontend in an iframe at the **Preview URL** set under **Settings > Visual Editor**, appending `_storyblok` and `_storyblok_tk[...]` query parameters. Editors' preview sessions are tracked like real visitors. Point the Preview URL at a separate preview deployment registered as its own site in Rybbit, or leave the tag out of builds that use the preview token.
* **Preview parameters in tracked URLs**: if the same deployment serves both the live site and the Visual Editor, the `_storyblok` parameters show up in tracked page URLs. Add `data-track-query="false"` to the script tag to drop query strings.
* **The Storyblok app is not tracked**: the snippet only runs in your frontend, so time spent in `app.storyblok.com` never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Strapi (/docs/guides/strapi)





Strapi is a headless CMS: it exposes your content over a REST or GraphQL API and does not render your website. The tracking snippet therefore goes into the frontend that consumes the Strapi API, not into Strapi.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Strapi [#add-the-snippet-to-strapi]

    <Callout type="info">
      Strapi has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Strapi.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Strapi frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Nuxt is a popular Strapi frontend. Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby)
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **The admin panel is not tracked**: the Strapi admin at `/admin` is served by the Strapi server, not by your frontend, so it never loads the snippet. Content editors' activity does not appear in Rybbit, which is usually what you want.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# systeme.io (/docs/guides/systeme-io)





systeme.io has an account-wide **Tracking code** setting under **Settings > Sales Funnels** that adds code to every funnel page, plus a per-page **Tracking** section with a header field in the page editor. Use the account-wide setting unless you only want to track certain pages.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to systeme.io [#add-the-snippet-to-systemeio]

    <Tabs items="[&#x22;All funnels&#x22;, &#x22;One page&#x22;]">
      <Tab>
        1. Click your **profile picture** in the top-right corner and choose **Settings**.
        2. Select **Sales Funnels** in the left menu.
        3. Paste the snippet into the **Tracking code** box and click **Save**.

        The code is added to every page in every funnel on the account.
      </Tab>

      <Tab>
        1. Open the funnel, select the page in the list on the left and click **Edit page**.
        2. Click **Settings** in the upper-left corner of the editor and scroll to the **Tracking** section.
        3. Paste the snippet into the **header** field (the one for code that belongs between `<head>` and `</head>`).
        4. Save the page.
      </Tab>
    </Tabs>

    Paste only the `<script>` tag. systeme.io asks that custom code never include `<head>`, `<body>` or `<html>` tags of its own.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Duplicate pageviews**: the snippet is in both the account-wide Tracking code and a page's Tracking section. Keep one.
* **Not visible in preview**: custom code runs on the live page only. Open the published funnel URL to test.
* **Pages outside funnels**: the Sales Funnels tracking code covers funnel pages. Blog and course pages have their own settings, so add the snippet there if you want that traffic in the same site.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Tauri (/docs/guides/tauri)





Tauri v2 bundles your frontend into the app and serves it to the system webview. Install the `@rybbit/js` SDK in the frontend (or put the snippet in its `index.html`), then allow `https://app.rybbit.io` in the `app.security.csp` block of `src-tauri/tauri.conf.json`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Tauri [#add-the-snippet-to-tauri]

    <Callout type="info">
      Tauri's security guide advises against loading remote scripts such as CDN-hosted files. The SDK keeps all executable code inside the bundle, so it is the recommended method.
    </Callout>

    <Tabs items="[&#x22;@rybbit/js SDK&#x22;, &#x22;Script tag&#x22;]">
      <Tab>
        1. Install the package in your frontend project:

        ```bash
        npm install @rybbit/js
        ```

        2. Initialise it once in the frontend entry file (`src/main.ts` or equivalent):

        ```ts title="src/main.ts"
        import rybbit from "@rybbit/js";

        await rybbit.init({
          analyticsHost: "https://app.rybbit.io/api",
          siteId: "YOUR_SITE_ID",
        });
        ```

        3. Allow the analytics host in `connect-src`. Keep `ipc:` and `http://ipc.localhost`, which Tauri needs for frontend-to-Rust calls:

        ```json title="src-tauri/tauri.conf.json"
        {
          "app": {
            "security": {
              "csp": {
                "default-src": "'self'",
                "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]
              }
            }
          }
        }
        ```
      </Tab>

      <Tab>
        1. Paste the snippet into the `<head>` of your frontend's `index.html`:

        ```html title="index.html"
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        2. Allow the host in both `script-src` and `connect-src`:

        ```json title="src-tauri/tauri.conf.json"
        {
          "app": {
            "security": {
              "csp": {
                "default-src": "'self'",
                "script-src": ["'self'", "https://app.rybbit.io"],
                "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    If `app.security.csp` is unset, Tauri applies no CSP and neither change is needed. Route changes inside the app are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Works in `tauri dev` but not in the built app on macOS, Linux or iOS**: in development the frontend is served from your dev server (`http://localhost:1420` by default), which is a normal http origin. Production builds serve it from `http://tauri.localhost` on Windows and Android but from the custom scheme `tauri://localhost` on macOS, Linux and iOS. Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so requests from `tauri://localhost` are blocked by the webview. On Windows and Android, `app.windows[].useHttpsScheme: true` switches the origin to `https://tauri.localhost`; both forms work.
* **CSP violation in the webview console**: the message names the blocked directive. Add `https://app.rybbit.io` there; the SDK only needs `connect-src`, the script tag also needs `script-src`.
* **Object vs string CSP**: `app.security.csp` accepts either a single policy string or the object form shown above. Do not mix the two.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Teachable (/docs/guides/teachable)





Teachable adds tracking scripts through **Code Snippets** in the school admin, where the **Head Code Snippets** section places code inside the `<head>` of every page of your school. Code Snippets are available on the Builder plan and above.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Teachable [#add-the-snippet-to-teachable]

    1. In the school admin, go to **Site > Code Snippets**.
    2. Paste the snippet into the **Head Code Snippets** section, which applies to all pages and all users.
    3. Click **Save**.

    The **Logged In Snippets** and **Logged Out Snippets** sections restrict code to one audience. Leave them empty for Rybbit so students and prospects are tracked alike; if you only want to measure the public site, use **Logged Out Snippets** instead of the head section.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Code Snippets is missing from the Site menu**: it needs the Builder plan or higher. Schools on lower plans cannot add custom scripts.
* **Checkout and login pages are not tracked**: head code snippets do not apply to SSO-based login or checkout pages served from `sso.teachable.com`. Pages on your school domain, including the course area, are covered.
* **Snippet pasted into a lesson's Custom HTML block**: that block only affects one lesson. Use **Code Snippets** for site-wide tracking.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Thinkific (/docs/guides/thinkific)





Thinkific adds custom scripts through the **Site Footer Code** field under **Settings > Code & Analytics**. The code runs at the bottom of every page, including the Course Player, and editing it is available on paid plans (Basic or higher). Placing the snippet in the footer rather than the head is fine: it loads with `defer`, so timing is the same.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Thinkific [#add-the-snippet-to-thinkific]

    1. In the admin dashboard, go to **Settings** and open the **Code & Analytics** tab.
    2. Paste the snippet into **Site Footer Code**.
    3. Save.

    See Thinkific's [Site Footer Code](https://support.thinkific.com/hc/en-us/articles/360030724953-Site-Footer-Code) article for the field's current limits. Lesson changes inside the Course Player happen without a page reload; Rybbit tracks them as pageviews automatically as the URL changes.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Field is read-only or missing**: editing Site Footer Code needs a paid plan (Basic or higher).
* **Checkout is not tracked**: Site Footer Code does not run on Performance Checkout pages, so purchases complete outside Rybbit's view. Track the enrolment from the first page a student lands on after checkout, or use a webhook on your side.
* **Community pages are not tracked**: pages where students post and comment, and direct-messaging pages, are excluded from Site Footer Code by default.
* **Per-page footer code**: individual site pages also accept footer code in their page settings. Keep the site-wide field as the single place for the snippet so pages are not tracked twice.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ThriveCart (/docs/guides/thrivecart)





ThriveCart lets you add custom scripts to each checkout page, and its success page is where the purchase event goes. ThriveCart strips `data-*` attributes from script tags, so the site ID must travel in the script URL, as it does in the snippet below.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ThriveCart [#add-the-snippet-to-thrivecart]

    1. In your ThriveCart dashboard, open the checkout page you want to track.
    2. Open **Settings > Tracking**, the custom scripts section.
    3. Paste the snippet into the header scripts field and save.

    Repeat for each checkout page. If checkout runs on a subdomain such as `sales.yourdomain.com` and your main site uses the same site ID, both are tracked as one site, so funnels can follow a visitor from your site through to the purchase.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

ThriveCart also interferes with how inline events fire, so the success-page script below loads the tracker itself if it is missing, waits for it, and uses `sessionStorage` to send the event once per browser session even if the visitor refreshes or navigates back.

Add it to the checkout's **success page** and fill in the values at the top:

```html
<script>
(function () {
  var EVENT_NAME = "purchase";
  var PAYLOAD = { content_name: "Your Product Name", value: 97.0, currency: "USD" };
  var SITE_ID = "YOUR_SITE_ID";
  var SCRIPT_SRC = "https://app.rybbit.io/api/script.js?siteId=" + SITE_ID;

  // Send once per session, even on refresh or back navigation
  var SENT_KEY = "rybbit_" + EVENT_NAME + "_sent_v1";
  try {
    if (sessionStorage.getItem(SENT_KEY) === "1") return;
    sessionStorage.setItem(SENT_KEY, "1");
  } catch (e) {}

  function isReady() {
    return window.rybbit && typeof window.rybbit.event === "function";
  }
  function send() {
    window.rybbit.event(EVENT_NAME, PAYLOAD);
  }
  function waitThenSend(timeoutMs) {
    var start = Date.now();
    (function check() {
      if (isReady()) return send();
      if (Date.now() - start < timeoutMs) setTimeout(check, 150);
    })();
  }

  if (isReady()) return send();
  if (!document.querySelector('script[src="' + SCRIPT_SRC + '"]')) {
    var s = document.createElement("script");
    s.src = SCRIPT_SRC;
    s.defer = true;
    document.head.appendChild(s);
  }
  waitThenSend(8000);
})();
</script>
```

* `EVENT_NAME`: the event name, for example `purchase` or `checkout_complete`.
* `PAYLOAD`: `content_name` (product name), `value` (amount) and `currency` (`USD`, `GBP`, `EUR` and so on).
* `SITE_ID`: your Rybbit site ID.

Selling several products? The payload is fixed per page, so use a separate success page per product, or fill `PAYLOAD` from ThriveCart's dynamic variables where they are available.

## Troubleshooting [#troubleshooting]

* **Script attributes are stripped**: ThriveCart removes `data-*` attributes, so [script attributes](/docs/script#script-attributes) such as `data-skip-patterns` do not work here. Keep the site ID in the URL.
* **Duplicate purchase events**: the script is guarded by `sessionStorage`. If you still see duplicates, make sure the event script is on the success page only once, and clear session storage before testing again.
* **Script blocked**: if `script.js` never loads, try the footer scripts field instead of the header, or ask ThriveCart support to confirm custom scripts are enabled on your account.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# TYPO3 (/docs/guides/typo3)





TYPO3 sitepackages build the page `<head>` from TypoScript rather than an HTML template, so the snippet is added as a `page.includeJS` entry in your sitepackage's `setup.typoscript`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to TYPO3 [#add-the-snippet-to-typo3]

    1. Open your main TypoScript setup file, usually `<sitepackage>/Configuration/TypoScript/setup.typoscript`. It is the file that already contains `page = PAGE`. The same TypoScript can also live in a TypoScript record in the backend.

    2. Add the script to the `page` object:

       ```
       page = PAGE
       page {
         includeJS {
           rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
           rybbit.defer = 1
         }
       }
       ```

       Because the Site ID is part of the URL, no `data-*` attribute is needed, so this works on every supported TYPO3 version. Per-include attributes on `includeJS` only exist in TYPO3 12.1+.

    3. To track production only, wrap the include in an `applicationContext` condition:

       ```
       [applicationContext == "Production"]
       page.includeJS.rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
       page.includeJS.rybbit.defer = 1
       [END]
       ```

    4. Optionally keep the Site ID and instance URL in `constants.typoscript` (or a TypoScript record) so the setup file can be committed without site-specific values:

       ```
       # constants.typoscript
       rybbit {
         host = https://app.rybbit.io
         siteId = YOUR_SITE_ID
       }

       # setup.typoscript
       page.includeJS.rybbit = {$rybbit.host}/api/script.js?siteId={$rybbit.siteId}
       page.includeJS.rybbit.defer = 1
       ```

    5. Deploy the sitepackage, or set `applicationContext` accordingly, and flush the TYPO3 caches.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Script not in the page source**: TYPO3 caches rendered pages. Flush caches from the backend toolbar or with `vendor/bin/typo3 cache:flush` after changing TypoScript.
* **Wrong TypoScript file**: if several files define `page`, check the resulting `page.includeJS` in the TypoScript object browser in the backend to see which definition wins.
* **Condition never matches**: the `applicationContext` is set through the `TYPO3_CONTEXT` environment variable. If it is unset, TYPO3 runs as `Production` and the script loads everywhere.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Umbraco (/docs/guides/umbraco)





Umbraco renders pages with Razor templates stored as `.cshtml` files in the `Views` folder and edited in the backoffice under **Settings > Templates**. A fresh install has no templates until you create one, so the snippet goes into the master (layout) template that your page templates set as their `Layout`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Umbraco [#add-the-snippet-to-umbraco]

    1. In the backoffice, open the **Settings** section and expand **Templates**.
    2. Open the master template that the other templates use as their layout (named `Master&#x60; in Umbraco's own tutorial). If you have none yet, click &#x2A;*...** next to **Templates**, choose **Create**, and move the shared `<html>`, `<head>` and `<body>` markup into it.
    3. Add the tag before `</head>` and click **Save**:

    ```razor title="Views/Master.cshtml"
    @using Umbraco.Cms.Web.Common.PublishedModels;
    @inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
    @{
        Layout = null;
    }
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8" />
        <title>@Model.Name</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        @RenderBody()
    </body>
    </html>
    ```

    4. Check that each page template points at it, for example `Layout = "Master.cshtml";`. Templates with `Layout = null;` render their own `<head>` and need the tag added directly.

    Saving in the backoffice writes the same file to `Views/Master.cshtml` in the project, so you can also edit it in your IDE and commit it.

    To keep the site ID out of the template, put it in `appsettings.json` and read it with `@Configuration["Rybbit:SiteId"]` after injecting `IConfiguration`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Change not visible**: Razor views are compiled on first request; if you edited the file outside the backoffice on a published site, restart the app or redeploy. Also clear any output cache or CDN in front of the site.
* **Preview counts as visits**: the backoffice **Preview** button renders your template with unpublished content, so editors' previews are tracked like any other visit. Wrap the tag in `@if (!UmbracoContext.InPreviewMode) { ... }` to leave them out.
* **Backoffice is not tracked**: `/umbraco` is a separate app that does not use your templates, so editing time never appears in Rybbit.
* **Several master templates**: a multi-site install with one layout per site needs the tag in each, or in a partial view rendered from every layout with `@await Html.PartialAsync("Rybbit")`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Unbounce (/docs/guides/unbounce)





Unbounce's **Script Manager** applies a script to every page on a domain, including pages you publish later, so that is where the snippet goes. If you only want to track a single Classic Builder page, the page-level **Javascripts** dialog works too.

<Callout type="warn">
  Custom scripts and pixels are not available on the Starter plan; you need Build or higher. Script Manager also requires a connected custom domain: it does not apply to pages on the `unbouncepages.com` test domain.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Unbounce [#add-the-snippet-to-unbounce]

    <Tabs items="[&#x22;Script Manager&#x22;, &#x22;Classic Builder page&#x22;]">
      <Tab>
        1. In the left menu, click **Settings**, then **Script Manager**.
        2. Click **Add a Script**, choose **Custom Script**, give it a name and click **Add Script Details**.
        3. Set **Placement** to **Head** and **Included on** to **All** (main pages and confirmation dialogs).
        4. Paste the snippet into the editor.
        5. Tick the domain(s) the script should apply to on the right, then click **Save Changes**.

        The script is added to every page on those domains and to new pages published there later. If a page does not pick it up, republish that page.
      </Tab>

      <Tab>
        1. Open the page in the Classic Builder and click **Javascripts** in the bottom-left corner.
        2. Give the script a name and set **Placement** to **Head**.
        3. Paste the snippet and click **Done**.
        4. **Save**, then **Publish** (or **Republish**) the page. Custom scripts do not run in the builder or in Preview, only on the published page.

        Smart Builder pages have no page-level script dialog; use Script Manager for those.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Form submission [#form-submission]

Unbounce exposes `window.ub.hooks`, an unofficial hook that runs after a lead is recorded. Add this as a second Script Manager script (or page script) with placement **Before Body End Tag** to send a `lead` event with the page name and variant:

```html
<script>
window.ub.hooks.afterFormSubmit.push(function () {
  if (window.rybbit) {
    window.rybbit.event("lead", {
      page: window.ub.page.name,
      variant: window.ub.page.variantId
    });
  }
});
</script>
```

`window.ub.page.name`, `window.ub.page.variantId` and `window.ub.page.id` are available on every Unbounce page, so you can compare A/B variants in Rybbit without any other setup.

## Troubleshooting [#troubleshooting]

* **Script runs twice**: a script that is both in Script Manager and on an individual page loads twice. Remove the page-level copy and keep the Script Manager one.
* **Nothing on `unbouncepages.com`**: Script Manager only applies to custom domains. Add the snippet at page level to test on the Unbounce test domain.
* **Script Manager missing**: the account is on the Starter plan, which does not include custom scripts.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# v0 (/docs/guides/v0)





v0 generates Next.js apps, so there is no single `index.html` and no project setting for head code. The snippet goes into the root layout, `app/layout.tsx`, through a `next/script` tag that renders on every page. Ask v0 to add it or edit the file in the Code tab, then publish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to v0 [#add-the-snippet-to-v0]

    <Tabs items="[&#x22;Ask v0&#x22;, &#x22;Edit app/layout.tsx&#x22;]">
      <Tab>
        Paste this into the chat, with your site ID in place of the placeholder:

        ```text
        Add the Rybbit analytics script to the root layout (app/layout.tsx) using next/script with strategy="afterInteractive", so it loads on every page:
        https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
        ```

        Check the diff: the `<Script>` belongs in `app/layout.tsx`, not in a page or component.
      </Tab>

      <Tab>
        Select the **Code** tab in the preview toolbar, open `app/layout.tsx` and add the `Script` component inside `<body>`. The `defer` attribute from the snippet is not needed; the strategy handles timing.

        ```tsx title="app/layout.tsx"
        import Script from "next/script";

        export default function RootLayout({ children }: { children: React.ReactNode }) {
          return (
            <html lang="en">
              <body>
                {children}
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```

        Press **Cmd+S** / **Ctrl+S** to save.
      </Tab>
    </Tabs>

    Click **Publish** in the top right of the chat, then **Publish to Production**. Navigation through `<Link>` and `router.push()` is tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a client component. Guard the call, because v0 components can render on the server and the script loads after hydration.

```tsx title="components/signup-button.tsx"
"use client";

export function SignupButton() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Production has no script**: the preview updates on save, but the live site only changes after **Publish to Production**. Projects connected to GitHub go through a pull request that v0 merges before the production deployment runs.
* **v0 rewrote the layout**: a later prompt can regenerate `app/layout.tsx`. Add "keep the Rybbit Script tag in app/layout.tsx" to the project's custom instructions, and re-check the page source after large changes.
* **Pages Router**: if your project has `pages/` instead of `app/`, put the `Script` in `pages/_app.tsx` as shown in the [Next.js guide](/docs/guides/react/next-js).

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# VitePress (/docs/guides/vitepress)





VitePress has a `head` option in `.vitepress/config.ts` that adds tags to every page, which is where the snippet goes. A custom theme is the fallback when you need to load it conditionally at runtime.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to VitePress [#add-the-snippet-to-vitepress]

    <Tabs items="[&#x22;Config file&#x22;, &#x22;Custom theme&#x22;]">
      <Tab>
        Edit `.vitepress/config.ts` (or `.js` / `.mts`) and add the tag to `head`:

        ```typescript filename=".vitepress/config.ts"
        import { defineConfig } from "vitepress";

        export default defineConfig({
          // ... your other config
          head: [
            [
              "script",
              {
                src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                defer: "",
              },
            ],
          ],
        });
        ```

        <Callout type="info">
          The empty string for `defer` is intentional. VitePress renders it as a boolean attribute.
        </Callout>

        To track production only, make `head` conditional:

        ```typescript filename=".vitepress/config.ts"
        const isProd = process.env.NODE_ENV === "production";

        export default defineConfig({
          head: isProd
            ? [["script", { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: "" }]]
            : [],
        });
        ```
      </Tab>

      <Tab>
        If you need runtime control, inject the tag from a custom theme. Create or edit `.vitepress/theme/index.ts`:

        ```typescript filename=".vitepress/theme/index.ts"
        import { type Theme } from "vitepress";
        import DefaultTheme from "vitepress/theme";

        export default {
          extends: DefaultTheme,
          enhanceApp() {
            if (typeof window === "undefined") return;

            const el = document.createElement("script");
            el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
            el.defer = true;
            document.head.appendChild(el);
          },
        } satisfies Theme;
        ```

        The `window` check keeps the injector out of the server-side build.
      </Tab>
    </Tabs>

    VitePress navigates between pages client-side. Rybbit picks up those History API changes as pageviews, so no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in `vitepress dev`**: if you used the `isProd` guard, the tag only renders in `vitepress build`. Remove the guard to test locally.
* **Pageviews stop after navigation**: check the browser console for errors thrown by other `head` scripts or theme code; an exception during route change can block Rybbit's listener.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Webflow (/docs/guides/webflow)





Webflow accepts custom `<head>` code either site-wide in **Site settings → Custom code** or per page in the page settings. Either way the code only reaches the live site when you publish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Webflow [#add-the-snippet-to-webflow]

    <Tabs items="[&#x22;Site-wide&#x22;, &#x22;Single page&#x22;]">
      <Tab value="Site-wide">
        1. Open your project and go to **Site settings → Custom code**.
        2. Paste the snippet into **Head code**.
        3. Click **Save**, then **Publish** the site.
      </Tab>

      <Tab value="Single page">
        Use this when you only want to track specific pages.

        1. In the Designer, open the page's **Settings** (cog icon next to the page name).
        2. Scroll to **Custom code** and paste the snippet into **Inside `<head>` tag**.
        3. Click **Save**, then **Publish** the site.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Give the element an **ID** in the Designer (**Settings** panel → **General** → **ID**), then attach a listener in **Site settings → Custom code → Footer code** or in an **Embed** element on that page:

```html
<script>
  document.addEventListener("DOMContentLoaded", function () {
    var button = document.getElementById("my-special-button");
    if (!button) return;
    button.addEventListener("click", function () {
      window.rybbit?.event("button_click", {
        button_id: "my-special-button",
        page_path: window.location.pathname,
      });
    });
  });
</script>
```

The same pattern works for a Form Block's `submit` event. Webflow handles form submission itself, so this fires on the submit attempt, not on confirmed success.

## Troubleshooting [#troubleshooting]

* **Changes not showing on the live site**: custom code is staged until you **Publish**. Check the published site, not the Designer preview.
* **Interactions that show or hide sections** without changing the URL produce a single pageview. Track those states as custom events, or call `window.rybbit.pageview()` from your own script when they appear.
* **Scripts that read the DOM** belong in **Footer code**, not **Head code**, so the elements exist when they run.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Weebly (/docs/guides/weebly)





Weebly (now part of Square) has site-wide **Header Code** and **Footer Code** fields under its SEO settings. Header code is printed into the `<head>` of every page, so the snippet goes there and no theme edits are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Weebly [#add-the-snippet-to-weebly]

    1. Open your site in the Weebly editor and go to **Settings > SEO**.
    2. Paste the snippet into **Header Code** and click **Save**.
    3. Click **Publish**. Header code changes only reach the live site after you publish.

    If your editor has no **Settings** tab, the same header-code option is under **Website > General Settings** in the Square dashboard.

    Site-level header code covers every page, including blog posts. Each page also has its own **Header Code** box in its page settings; that one is for page-specific code and is not needed for the snippet.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the page source**: the site was not republished. Click **Publish** after every change to header code.
* **Snippet appears twice**: it was added both site-wide and on individual pages. Keep only the site-level entry under **Settings > SEO**.
* **Footer Code instead of Header Code**: both fields are included on every page, so the snippet works from either, but the footer loads later and misses visitors who leave early.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Wix (/docs/guides/wix)





Wix adds third-party scripts through the **Custom Code** panel in the site dashboard, where you choose which pages load the code and where in the document it goes.

<Callout type="warn">
  Custom code requires a **Wix Premium plan** and a **connected domain**. It is not available on free Wix sites.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Wix [#add-the-snippet-to-wix]

    1. Open your site's dashboard and go to **Settings**.
    2. Open **Custom Code** (under **Advanced**). Older dashboards list it as **Tracking Tools & Analytics** under **Marketing & SEO**.
    3. Click **+ Add Custom Code** and paste the snippet into the code box.
    4. Name the code, for example `Rybbit`.
    5. Under **Add Code to Pages**, choose **All pages** and **Load code once**. The script tracks Wix's client-side navigation itself, so loading it on every page change would inject it repeatedly.
    6. Under **Place Code in**, choose **Head**.
    7. Click **Apply**.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Custom Code is missing from Settings**: the site has no Premium plan or no connected domain. Both are required before the panel appears.
* **Duplicate pageviews**: the code was added with **Load code on each new page**. Edit the entry and switch to **Load code once**.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# WooCommerce (/docs/guides/woocommerce)





WooCommerce runs on WordPress, so the snippet goes in the same way as on any WordPress site. What this guide adds is the WooCommerce action hooks that send purchases, add-to-carts, product views and checkouts to Rybbit as custom events.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to WooCommerce [#add-the-snippet-to-woocommerce]

    Follow the [WordPress guide](/docs/guides/wordpress) to add the snippet. If you plan to track the e-commerce events below, use the `functions.php` or mini-plugin method there: the event hooks are PHP and belong in the same file.

    ```php
    function rybbit_add_tracking_script() {
        ?>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        <?php
    }
    add_action( 'wp_head', 'rybbit_add_tracking_script' );
    ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

WooCommerce fires PHP action hooks at each stage of the shopping flow. The snippets below print a small inline script from those hooks. They wait for `DOMContentLoaded` because the tracking script is loaded with `defer`, so `window.rybbit` does not exist while the page is still parsing.

<Callout type="warn">
  Add these to your &#x2A;*child theme's `functions.php`** or a site-specific plugin, never to the parent theme.
</Callout>

#### Purchase [#purchase]

`woocommerce_thankyou` fires on the order-received page with the order ID.

```php
add_action( 'woocommerce_thankyou', 'rybbit_track_purchase', 10, 1 );
function rybbit_track_purchase( $order_id ) {
    $order = wc_get_order( $order_id );
    if ( ! $order ) {
        return;
    }

    $items = array();
    foreach ( $order->get_items() as $item ) {
        $product = $item->get_product();
        $items[] = array(
            'item_id'   => $product && $product->get_sku() ? $product->get_sku() : $item->get_product_id(),
            'item_name' => $item->get_name(),
            'price'     => (float) $order->get_line_subtotal( $item, false, false ),
            'quantity'  => (int) $item->get_quantity(),
        );
    }

    $purchase = array(
        'transaction_id' => $order->get_order_number(),
        'value'          => (float) $order->get_total(),
        'tax'            => (float) $order->get_total_tax(),
        'shipping'       => (float) $order->get_shipping_total(),
        'currency'       => $order->get_currency(),
        'items'          => $items,
    );
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function () {
        window.rybbit.event('purchase', <?php echo wp_json_encode( $purchase ); ?>);
    });
    </script>
    <?php
}
```

Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.

#### Add to cart [#add-to-cart]

Two hooks cover both paths: the product-page form submit, and WooCommerce's `added_to_cart` jQuery event for AJAX buttons on shop and category pages.

```php
// Single product page: track on form submit
add_action( 'woocommerce_after_add_to_cart_button', 'rybbit_track_add_to_cart' );
function rybbit_track_add_to_cart() {
    global $product;
    if ( ! $product instanceof WC_Product ) {
        return;
    }
    $data = array(
        'item_id'   => $product->get_sku() ? $product->get_sku() : $product->get_id(),
        'item_name' => $product->get_name(),
        'price'     => (float) $product->get_price(),
        'currency'  => get_woocommerce_currency(),
    );
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function () {
        var form = document.querySelector('form.cart');
        if (!form) return;
        form.addEventListener('submit', function () {
            var data = <?php echo wp_json_encode( $data ); ?>;
            var qty = form.querySelector('input.qty');
            data.quantity = qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1;
            window.rybbit.event('add_to_cart', data);
        });
    });
    </script>
    <?php
}

// AJAX add-to-cart buttons on shop and category pages
add_action( 'wp_footer', 'rybbit_track_ajax_add_to_cart' );
function rybbit_track_ajax_add_to_cart() {
    if ( is_admin() ) {
        return;
    }
    ?>
    <script>
    jQuery(document.body).on('added_to_cart', function (event, fragments, cartHash, $button) {
        if (!$button || !$button.length) return;
        window.rybbit.event('add_to_cart', {
            item_id: $button.data('product_id'),
            quantity: $button.data('quantity') || 1,
            source: 'ajax_add_to_cart'
        });
    });
    </script>
    <?php
}
```

The AJAX handler only sees the product ID and quantity from the button's `data-*` attributes. Add attributes to the button in your theme if you also want name and price.

#### View product and begin checkout [#view-product-and-begin-checkout]

The same pattern works for the remaining hooks:

* `woocommerce_after_single_product_summary` runs on product pages. Guard with `is_product()`, then send `view_item` with `item_id`, `item_name`, `price` and `currency` from the global `$product`.
* `woocommerce_before_checkout_form` runs on the checkout page. Build `begin_checkout` from `WC()->cart`: loop over `get_cart()` for the items (each `$cart_item['data']` is the product, `$cart_item['quantity']` the quantity), with `value` from `$cart->get_total( 'edit' )` and `currency` from `get_woocommerce_currency()`.

## Troubleshooting [#troubleshooting]

* **Events fire before the tracker loads**: keep the tracking snippet in `wp_head` and the `DOMContentLoaded` wrapper in place. Deferred scripts run before `DOMContentLoaded`, so `window.rybbit` is ready by then; calling it from a bare inline script drops the event.
* **AJAX carts and mini-carts**: themes that update the cart without a page load never hit the PHP hooks, so rely on the `added_to_cart` listener for those and test each add-to-cart path.
* **Other analytics plugins**: plugins that also print e-commerce data layers can conflict. Test with a real order after enabling both.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# WordPress (/docs/guides/wordpress)





WordPress has no built-in header-code setting, so the snippet goes in through a plugin such as **WPCode** or through your theme's `functions.php` or `header.php`. Every method below works on self-hosted WordPress.org sites; on WordPress.com you need the Business plan or higher before you can install plugins or add custom JavaScript.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to WordPress [#add-the-snippet-to-wordpress]

    <Callout type="warn">
      If you edit theme files, edit a **child theme**. Changes to a parent theme's `functions.php` or `header.php` are lost on the next theme update.
    </Callout>

    <Tabs items="[&#x22;WPCode&#x22;, &#x22;functions.php&#x22;, &#x22;header.php&#x22;, &#x22;Mini plugin&#x22;]">
      <Tab>
        WPCode (formerly Insert Headers and Footers) is the recommended method: it survives theme updates, works with page builders, and is available on WordPress.com Business plans.

        1. Go to **Plugins > Add New**, search for "WPCode", then install and activate it.
        2. Go to **Code Snippets > Header & Footer** (**Settings > Insert Headers and Footers** in older versions).
        3. Paste the snippet into the **Header** box and click **Save Changes**.
      </Tab>

      <Tab>
        1. Go to **Appearance > Theme File Editor** and open your child theme's `functions.php`.
        2. Add this to the end of the file, replacing `YOUR_SITE_ID`:

        ```php
        function rybbit_add_tracking_script() {
            ?>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
            <?php
        }
        add_action( 'wp_head', 'rybbit_add_tracking_script' );
        ```

        3. Save the file.
      </Tab>

      <Tab>
        1. Go to **Appearance > Theme File Editor** and open your child theme's `header.php`.
        2. Paste the snippet just before the closing `</head>` tag:

        ```html
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        3. Save the file.
      </Tab>

      <Tab>
        A one-file plugin keeps the snippet in place through theme changes without touching theme files.

        1. Over FTP/SFTP or a file-manager plugin, create the folder `/wp-content/plugins/rybbit-analytics/`.
        2. Inside it, create `rybbit-analytics.php` with this content, replacing `YOUR_SITE_ID`:

        ```php
        <?php
        /**
         * Plugin Name: Rybbit Analytics
         * Description: Adds the Rybbit tracking script to every page
         * Version: 1.0
         */

        function rybbit_add_tracking_script() {
            ?>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
            <?php
        }
        add_action( 'wp_head', 'rybbit_add_tracking_script' );
        ```

        3. Go to **Plugins** and activate **Rybbit Analytics**.
      </Tab>
    </Tabs>

    Running WooCommerce? Once the snippet is in place, see the [WooCommerce guide](/docs/guides/woocommerce) for purchase and add-to-cart events.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Caching plugins**: after saving the snippet, purge WP Super Cache, W3 Total Cache, LiteSpeed Cache or whichever cache plugin you run, plus any CDN cache such as Cloudflare, before you check the page source.
* **Script optimisers**: "Delay JavaScript execution" features in WP Rocket, Perfmatters and FlyingPress rebuild script tags and drop `data-*` attributes, which is why the snippet passes the site ID in the URL (`?siteId=`). If tracking still fails, exclude `app.rybbit.io` from optimisation: Autoptimize's exclusion list, WP Rocket's JavaScript optimisation and delay-JS exclusions, Perfmatters / FlyingPress delay-JS exclusions, LiteSpeed Cache JS excludes, SG Optimizer combine/minify.
* **Page builders** (Elementor, Divi, WPBakery, Beaver Builder): add the snippet with WPCode rather than a builder's custom HTML block. Builders sanitise HTML and can strip attributes from script tags.
* **Security plugins**: Wordfence, Sucuri and similar plugins can block external scripts. Add `app.rybbit.io` to the allowlist.
* **WordPress.com plans**: Free, Personal and Premium plans cannot add custom JavaScript. Upgrade to Business or eCommerce and use the WPCode method.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Zola (/docs/guides/zola)





Zola pages extend a base Tera template, normally `templates/base.html`, so the snippet goes in that file's `<head>`. Keep the site ID in the `[extra]` section of `config.toml`, which every template can read as `config.extra`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Zola [#add-the-snippet-to-zola]

    1. Add your site ID under `[extra]` in `config.toml`. `rybbit_instance_url` is only needed if you self-host:

       ```toml title="config.toml"
       [extra]
       rybbit_site_id = "YOUR_SITE_ID"
       rybbit_instance_url = "https://app.rybbit.io"
       ```

    2. Open `templates/base.html` and add the tag inside `<head>`. The `config.mode` check keeps the script out of `zola serve`, so local development is not tracked:

       ```html title="templates/base.html"
       <head>
         ...
         {% if config.mode == "build" %}
           <script src="{{ config.extra.rybbit_instance_url }}/api/script.js?siteId={{ config.extra.rybbit_site_id }}" defer></script>
         {% endif %}
       </head>
       ```

       If a theme owns `base.html`, copy it from `themes/<theme>/templates/base.html` into your own `templates/` directory first. A template in your site with the same name overrides the theme's copy, so the theme can be updated without losing the change.

    3. Build and deploy the generated `public/` directory:

       ```bash
       zola build
       ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `zola serve` sets `config.mode` to `serve`, so the guard removes the tag. Check the output of `zola build` instead.
* **`config.mode` is not defined**: older Zola releases do not expose it. Upgrade, or drop the `if` block and accept local pageviews.
* **Pages without the tag**: templates that do not `{% extends "base.html" %}` (a custom `404.html`, or a section template that builds its own `<head>`) need the tag added separately.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Astro Proxy Setup (/docs/proxy-guide/astro)





Astro's middleware feature makes it simple to proxy Rybbit tracking. This guide shows how to set up server-side request proxying in your Astro application.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Astro middleware allows you to intercept and modify requests before they're handled, making it perfect for creating a transparent analytics proxy.

**What you'll achieve:**

* Proxy Rybbit endpoints through your Astro site
* Forward necessary headers for accurate tracking
* Simple configuration in `astro.config.mjs`
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Astro 2.0 or later (with SSR or hybrid rendering enabled)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

<Callout type="warn">
  This guide requires SSR (Server-Side Rendering) or hybrid mode. Static sites cannot proxy requests server-side. For static sites on platforms like Vercel or Netlify, use their platform-specific proxy configurations.
</Callout>

## Implementation [#implementation]

<Steps>
  ### Enable SSR in Astro [#enable-ssr-in-astro]

  Update `astro.config.mjs` to enable SSR:

  ```javascript
  // astro.config.mjs
  import { defineConfig } from 'astro/config';
  import node from '@astrojs/node';

  export default defineConfig({
    output: 'server', // or 'hybrid'
    adapter: node({
      mode: 'standalone',
    }),
  });
  ```

  Install the Node adapter if not already installed:

  ```bash
  npm install @astrojs/node
  ```

  ### Configure Environment Variables [#configure-environment-variables]

  Create or update `.env`:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  ### Create Middleware [#create-middleware]

  Create `src/middleware.ts` (or `.js` for JavaScript):

  ```typescript
  // src/middleware.ts
  import type { MiddlewareHandler } from 'astro';

  const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';

  export const onRequest: MiddlewareHandler = async (context, next) => {
    const { request } = context;
    const url = new URL(request.url);

    // Check if this is an analytics request
    if (url.pathname.startsWith('/analytics/')) {
      return proxyToRybbit(request, url.pathname);
    }

    // Continue with normal request handling
    return next();
  };

  async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
    try {
      // Map paths: /analytics/* → /api/*
      let rybbitPath = pathname.replace('/analytics/', '/api/');

      const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;

      // Get client IP from headers
      const forwardedFor = request.headers.get('x-forwarded-for');
      const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';

      // Forward request
      const proxyHeaders = new Headers(request.headers);
      proxyHeaders.set('X-Real-IP', clientIp);
      proxyHeaders.set('X-Forwarded-For', clientIp);

      const response = await fetch(rybbitUrl, {
        method: request.method,
        headers: proxyHeaders,
        body: request.method !== 'GET' ? await request.text() : undefined,
      });

      // Return proxied response
      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
      });
    } catch (error) {
      console.error('Rybbit proxy error:', error);
      return new Response('Analytics proxy error', { status: 500 });
    }
  }
  ```

  For JavaScript projects:

  ```javascript
  // src/middleware.js
  const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';

  export const onRequest = async (context, next) => {
    const { request } = context;
    const url = new URL(request.url);

    if (url.pathname.startsWith('/analytics/')) {
      return proxyToRybbit(request, url.pathname);
    }

    return next();
  };

  async function proxyToRybbit(request, pathname) {
    try {
      // Map paths: /analytics/* → /api/*
      let rybbitPath = pathname.replace('/analytics/', '/api/');

      const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;
      const forwardedFor = request.headers.get('x-forwarded-for');
      const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';

      const proxyHeaders = new Headers(request.headers);
      proxyHeaders.set('X-Real-IP', clientIp);
      proxyHeaders.set('X-Forwarded-For', clientIp);

      const response = await fetch(rybbitUrl, {
        method: request.method,
        headers: proxyHeaders,
        body: request.method !== 'GET' ? await request.text() : undefined,
      });

      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
      });
    } catch (error) {
      console.error('Rybbit proxy error:', error);
      return new Response('Analytics proxy error', { status: 500 });
    }
  }
  ```

  ### Update Your Layout [#update-your-layout]

  Add the tracking script to your layout:

  ```astro
  ---
  // src/layouts/Layout.astro
  const { title } = Astro.props;
  ---

  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width" />
      <title>{title}</title>

      <!-- Rybbit Analytics -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
    </head>
    <body>
      <slot />
    </body>
  </html>
  ```

  ### Start Development Server [#start-development-server]

  ```bash
  npm run dev
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Open your site** in a browser with Developer Tools
  2. **Check Network tab**: Requests should go to `/analytics/*`
  3. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Astro middleware intercepts requests before they're processed:

1. Request to `/analytics/script.js` enters middleware
2. Middleware proxies to `https://app.rybbit.io/api/script.js`
3. Client IP headers are preserved
4. Response is returned to browser

## Advanced Configuration [#advanced-configuration]

### Caching with Astro [#caching-with-astro]

Add caching for scripts:

```typescript
// src/middleware.ts
const cache = new Map<string, { response: Response; timestamp: number }>();
const CACHE_TTL = 3600000; // 1 hour in milliseconds

async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
  // Cache GET requests for scripts
  if (request.method === 'GET' && pathname.endsWith('.js')) {
    const cached = cache.get(pathname);

    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
      return cached.response.clone();
    }
  }

  // ... proxy logic

  // Cache the response
  if (request.method === 'GET' && pathname.endsWith('.js')) {
    cache.set(pathname, {
      response: response.clone(),
      timestamp: Date.now(),
    });
  }

  return response;
}
```

### Conditional Proxying [#conditional-proxying]

Only proxy in production:

```typescript
export const onRequest: MiddlewareHandler = async (context, next) => {
  const { request } = context;
  const url = new URL(request.url);

  // Only proxy in production
  if (import.meta.env.PROD && url.pathname.startsWith('/analytics/')) {
    return proxyToRybbit(request, url.pathname);
  }

  return next();
};
```

### Error Logging [#error-logging]

Add detailed error logging:

```typescript
async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
  try {
    // ... proxy logic
  } catch (error) {
    const errorDetails = {
      message: error instanceof Error ? error.message : 'Unknown error',
      pathname,
      method: request.method,
      timestamp: new Date().toISOString(),
    };

    console.error('Rybbit proxy error:', errorDetails);

    // Return error response
    return new Response(JSON.stringify({ error: 'Analytics proxy error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}
```

## Troubleshooting [#troubleshooting]

### Middleware not running [#middleware-not-running]

**Problem**: Requests bypass middleware.

**Solution**:

1. Ensure SSR or hybrid mode is enabled in `astro.config.mjs`
2. Verify middleware file is in `src/middleware.ts` (not in subdirectory)
3. Check adapter is installed: `npm install @astrojs/node`

### Static build issues [#static-build-issues]

**Problem**: Build fails or proxy doesn't work in production.

**Solution**:
Middleware requires server-side rendering. Ensure:

```javascript
// astro.config.mjs
export default defineConfig({
  output: 'server', // Required for middleware
  adapter: node({
    mode: 'standalone',
  }),
});
```

### Environment variables not loading [#environment-variables-not-loading]

**Problem**: `RYBBIT_HOST` is undefined.

**Solution**:

1. Check `.env` file is in project root
2. Use `import.meta.env.RYBBIT_HOST` (not `process.env`)
3. For production, set environment variables in your hosting platform

## Deployment [#deployment]

### Vercel [#vercel]

Deploy with Vercel adapter:

```bash
npm install @astrojs/vercel
```

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});
```

### Netlify [#netlify]

Deploy with Netlify adapter:

```bash
npm install @astrojs/netlify
```

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify/functions';

export default defineConfig({
  output: 'server',
  adapter: netlify(),
});
```

### Node.js Server [#nodejs-server]

For self-hosting:

```bash
npm run build
node ./dist/server/entry.mjs
```

## Related Resources [#related-resources]

* [Astro Integration Guide](/docs/guides/astro) - General Astro integration
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Astro Middleware](https://docs.astro.build/en/guides/middleware/) - Official Astro docs


# Caddy Proxy Setup (/docs/proxy-guide/caddy)





Caddy is a powerful web server with automatic HTTPS that makes reverse proxying simple and secure. This guide shows how to configure Caddy to proxy Rybbit tracking through your own domain.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Caddy's `reverse_proxy` directive makes it incredibly easy to proxy requests. Combined with automatic HTTPS via Let's Encrypt, Caddy provides a secure, low-configuration solution for proxying analytics.

**What you'll achieve:**

* Automatic HTTPS with Let's Encrypt
* Simple reverse proxy configuration
* Header forwarding for accurate tracking
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Caddy installed (version 2.0 or later)
* Domain pointing to your server
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID (found in your dashboard)

<Callout type="info">
  Caddy automatically obtains and renews SSL certificates from Let's Encrypt. No manual SSL configuration needed!
</Callout>

## Implementation [#implementation]

<Steps>
  ### Configure Caddyfile [#configure-caddyfile]

  Add or update your Caddyfile with the analytics proxy configuration:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'Simplified with Handle Path']">
    <Tab>
      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          # Your main site configuration
          # ...

          # Rybbit Analytics Proxy
          # Main tracking script
          handle /analytics/script.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up X-Forwarded-Proto {scheme}
              }
              rewrite * /api/script.js
          }

          # Session replay script
          handle /analytics/replay.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/replay.js
          }

          # Web Vitals metrics script
          handle /analytics/metrics.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/metrics.js
          }

          # Event tracking endpoint
          handle /analytics/track {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/track
          }

          # User identification endpoint
          handle /analytics/identify {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/identify
          }

          # Session replay recording
          handle /analytics/session-replay/record/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/session-replay/record{path}
          }

          # Site configuration
          handle /analytics/site/tracking-config/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/site/tracking-config{path}
          }
      }
      ```

      <Callout type="info">
        Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
      </Callout>
    </Tab>

    <Tab>
      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          # Main tracking script
          handle /analytics/script.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/script.js
          }

          # Event tracking
          handle /analytics/track {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/track
          }
      }
      ```
    </Tab>

    <Tab>
      Caddy 2.4+ supports a cleaner syntax with `handle_path`:

      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          handle_path /analytics/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api{uri}
          }
      }
      ```

      This proxies all `/analytics/*` requests to `https://app.rybbit.io/api/*`.
    </Tab>
  </Tabs>

  ### Validate Caddyfile [#validate-caddyfile]

  Test your configuration for syntax errors:

  ```bash
  caddy validate --config /etc/caddy/Caddyfile
  ```

  You should see:

  ```
  Valid configuration
  ```

  ### Reload Caddy [#reload-caddy]

  Apply the changes by reloading Caddy:

  ```bash
  sudo caddy reload --config /etc/caddy/Caddyfile
  ```

  Or if using systemd:

  ```bash
  sudo systemctl reload caddy
  ```

  <Callout type="info">
    Caddy will automatically obtain an SSL certificate from Let's Encrypt on first request if one doesn't exist.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to load the script from your proxied domain:

  ```html
  <!DOCTYPE html>
  <html>
  <head>
      <!-- ... other head elements -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      <!-- Your content -->
  </body>
  </html>
  ```

  Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.

  ### Verify the Setup [#verify-the-setup]

  Test your configuration:

  1. **Check Caddy is running**:
     ```bash
     sudo systemctl status caddy
     ```

  2. **Test script loading**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see `HTTP/2 200` with `content-type: application/javascript`.

  3. **Open your website** in a browser with Developer Tools and verify:
     * Script loads from `/analytics/script.js`
     * Tracking requests go to `/analytics/track`
     * Data appears in Rybbit dashboard
</Steps>

## How It Works [#how-it-works]

Caddy's `reverse_proxy` directive forwards requests to Rybbit's servers:

1. Browser requests `https://yourdomain.com/analytics/script.js`
2. Caddy matches the handle block
3. Rewrites the path to `/api/script.js`
4. Forwards to `https://app.rybbit.io/api/script.js` with proper headers
5. Returns response to browser

The Rybbit script auto-detects it's being served from your domain and sends all tracking to your domain's endpoints.

## Advanced Configuration [#advanced-configuration]

### Caching with Cache-Control [#caching-with-cache-control]

Add caching headers for better performance:

```txt
yourdomain.com {
    # Scripts - cache for 1 hour
    handle /analytics/script.js {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/script.js
        header Cache-Control "public, max-age=3600"
    }

    # Config - cache for 5 minutes
    handle /analytics/site/tracking-config/* {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/site/tracking-config{path}
        header Cache-Control "public, max-age=300"
    }

    # Tracking - no cache
    handle /analytics/track {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/track
        header Cache-Control "no-store"
    }
}
```

### Subdomain Proxy [#subdomain-proxy]

Use a dedicated subdomain for analytics:

```txt
# /etc/caddy/Caddyfile

analytics.yourdomain.com {
    reverse_proxy https://app.rybbit.io {
        header_up Host app.rybbit.io
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
    }
    rewrite * /api{uri}
}
```

Then use:

```html
<script src="https://analytics.yourdomain.com/script.js" data-site-id="123"></script>
```

### Request Size Limits [#request-size-limits]

For session replay, increase max body size:

```txt
yourdomain.com {
    # Increase request body limit for session replay
    handle /analytics/session-replay/record/* {
        request_body {
            max_size 10MB
        }
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/session-replay/record{path}
    }
}
```

### Environment-Based Configuration [#environment-based-configuration]

Use Caddy's environment variable support:

```txt
# /etc/caddy/Caddyfile

{$DOMAIN:yourdomain.com} {
    handle_path /analytics/* {
        reverse_proxy {$RYBBIT_HOST:https://app.rybbit.io} {
            header_up Host {upstream_hostport}
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api{uri}
    }
}
```

Then set environment variables:

```bash
export DOMAIN=yourdomain.com
export RYBBIT_HOST=https://app.rybbit.io
caddy run
```

### Rate Limiting [#rate-limiting]

Protect your proxy with rate limiting using the `rate_limit` plugin:

```txt
yourdomain.com {
    handle /analytics/track {
        rate_limit {
            zone analytics {
                key {remote_host}
                events 100
                window 1m
            }
        }
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/track
    }
}
```

<Callout type="warn">
  The `rate_limit` directive requires the [caddy-ratelimit plugin](https://github.com/mholt/caddy-ratelimit). Install with: `xcaddy build --with github.com/mholt/caddy-ratelimit`
</Callout>

## Troubleshooting [#troubleshooting]

### Certificate errors [#certificate-errors]

**Problem**: Caddy fails to obtain SSL certificate.

**Solution**:

1. Verify domain points to your server (DNS)
2. Check ports 80 and 443 are open
3. Ensure no other process is using port 443
4. Check Caddy logs: `journalctl -u caddy -f`

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show same location.

**Solution**:
Ensure you're forwarding client IP:

```txt
reverse_proxy https://app.rybbit.io {
    header_up X-Real-IP {remote_host}
    header_up X-Forwarded-For {remote_host}
}
```

### 502 Bad Gateway [#502-bad-gateway]

**Problem**: Caddy returns 502 when accessing analytics endpoints.

**Solution**:

1. Verify Rybbit backend is accessible:
   ```bash
   curl -I https://app.rybbit.io/api/script.js
   ```
2. Check Caddy logs for errors:
   ```bash
   journalctl -u caddy -n 50
   ```

### Path rewriting not working [#path-rewriting-not-working]

**Problem**: Requests go to wrong Rybbit endpoints.

**Solution**:
Use the `rewrite` directive correctly:

```txt
handle /analytics/script.js {
    rewrite * /api/script.js  # Rewrite before reverse_proxy
    reverse_proxy https://app.rybbit.io {
        # ... headers
    }
}
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Framework-agnostic concepts
* [Caddy Documentation](https://caddyserver.com/docs/) - Official Caddy docs
* [Caddy reverse\_proxy](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) - Reverse proxy directive docs


# Cloudflare Workers Proxy Setup (/docs/proxy-guide/cloudflare-workers)





Cloudflare Workers provide a serverless way to proxy Rybbit tracking at the edge, close to your users worldwide. This delivers excellent performance with minimal configuration.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Cloudflare Workers run on Cloudflare's global network, intercepting and proxying requests before they reach your origin server. This makes them perfect for analytics proxying with built-in caching and ultra-low latency.

**What you'll achieve:**

* Edge-based proxying in 300+ cities worldwide
* Automatic caching with Cloudflare's Cache API
* Sub-10ms latency for most requests
* Zero server infrastructure needed

## Prerequisites [#prerequisites]

* Cloudflare account with your domain
* Workers enabled on your account (free tier available)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Create Worker [#create-worker]

  Log in to Cloudflare Dashboard and create a new Worker:

  1. Go to **Workers & Pages** → **Create application** → **Create Worker**
  2. Name it `rybbit-proxy` (or your preferred name)
  3. Click **Deploy** to create the worker

  ### Update Worker Code [#update-worker-code]

  Replace the default code with the proxy implementation:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'With Environment Variables']">
    <Tab>
      ```javascript
      // Cloudflare Worker for Rybbit Analytics Proxy

      const RYBBIT_HOST = 'https://app.rybbit.io';

      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request));
      });

      async function handleRequest(request) {
        const url = new URL(request.url);

        // Only proxy /analytics/* paths
        if (!url.pathname.startsWith('/analytics/')) {
          // Pass through to origin
          return fetch(request);
        }

        try {
          return await proxyToRybbit(request, url);
        } catch (error) {
          console.error('Proxy error:', error);
          return new Response('Analytics proxy error', { status: 500 });
        }
      }

      async function proxyToRybbit(request, url) {
        // Map paths: /analytics/* → /api/*
        let rybbitPath = url.pathname.replace('/analytics/', '/api/');

        // Build Rybbit URL
        const rybbitUrl = new URL(rybbitPath, RYBBIT_HOST);
        rybbitUrl.search = url.search; // Preserve query params

        // Get client IP
        const clientIp = request.headers.get('CF-Connecting-IP') ||
                         request.headers.get('X-Forwarded-For') ||
                         '0.0.0.0';

        // Build request headers
        const proxyHeaders = new Headers(request.headers);
        proxyHeaders.set('X-Real-IP', clientIp);
        proxyHeaders.set('X-Forwarded-For', clientIp);
        proxyHeaders.delete('CF-Connecting-IP'); // Remove Cloudflare internal header

        // Build proxy request
        const proxyRequest = new Request(rybbitUrl, {
          method: request.method,
          headers: proxyHeaders,
          body: request.method !== 'GET' && request.method !== 'HEAD' ? request.body : undefined,
        });

        // Check cache for GET requests
        if (request.method === 'GET') {
          const cache = caches.default;
          let response = await cache.match(proxyRequest);

          if (response) {
            // Return cached response
            return new Response(response.body, {
              status: response.status,
              statusText: response.statusText,
              headers: {
                ...Object.fromEntries(response.headers),
                'X-Cache-Status': 'HIT',
              },
            });
          }
        }

        // Fetch from Rybbit
        const response = await fetch(proxyRequest);

        // Cache scripts for 1 hour
        if (request.method === 'GET' && url.pathname.match(/\.(js)$/)) {
          const cacheResponse = new Response(response.body, response);
          cacheResponse.headers.set('Cache-Control', 'public, max-age=3600');
          cacheResponse.headers.set('X-Cache-Status', 'MISS');

          // Clone and cache
          const cache = caches.default;
          await cache.put(proxyRequest, cacheResponse.clone());

          return cacheResponse;
        }

        // Return non-cacheable response
        return new Response(response.body, {
          status: response.status,
          statusText: response.statusText,
          headers: response.headers,
        });
      }
      ```
    </Tab>

    <Tab>
      ```javascript
      // Minimal Cloudflare Worker for Rybbit

      const RYBBIT_HOST = 'https://app.rybbit.io';

      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request));
      });

      async function handleRequest(request) {
        const url = new URL(request.url);

        // Only proxy /analytics/script.js and /analytics/track
        if (url.pathname === '/analytics/script.js' || url.pathname === '/analytics/track') {
          const rybbitPath = url.pathname.replace('/analytics/', '/api/');
          const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;

          const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

          const proxyHeaders = new Headers(request.headers);
          proxyHeaders.set('X-Real-IP', clientIp);
          proxyHeaders.set('X-Forwarded-For', clientIp);

          return fetch(rybbitUrl, {
            method: request.method,
            headers: proxyHeaders,
            body: request.method === 'POST' ? request.body : undefined,
          });
        }

        // Pass through to origin
        return fetch(request);
      }
      ```
    </Tab>

    <Tab>
      Using Workers secrets for configuration:

      ```javascript
      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request, event.env));
      });

      async function handleRequest(request, env) {
        const RYBBIT_HOST = env.RYBBIT_HOST || 'https://app.rybbit.io';
        const url = new URL(request.url);

        if (!url.pathname.startsWith('/analytics/')) {
          return fetch(request);
        }

        // Map paths: /analytics/* → /api/*
        let rybbitPath = url.pathname.replace('/analytics/', '/api/');

        const rybbitUrl = new URL(rybbitPath, RYBBIT_HOST);
        const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

        const proxyHeaders = new Headers(request.headers);
        proxyHeaders.set('X-Real-IP', clientIp);
        proxyHeaders.set('X-Forwarded-For', clientIp);

        return fetch(rybbitUrl.toString(), {
          method: request.method,
          headers: proxyHeaders,
          body: request.method !== 'GET' ? request.body : undefined,
        });
      }
      ```

      Set environment variable in Cloudflare Dashboard:
      **Workers & Pages** → Your Worker → **Settings** → **Variables** → Add `RYBBIT_HOST`
    </Tab>
  </Tabs>

  ### Deploy Worker [#deploy-worker]

  Click **Save and Deploy** to publish your worker.

  ### Configure Worker Route [#configure-worker-route]

  Set up a route to trigger the worker:

  1. Go to **Workers & Pages** → Your Worker → **Triggers**
  2. Click **Add route**
  3. Configure:
     * **Route**: `yourdomain.com/analytics/*`
     * **Zone**: Select your domain
  4. Click **Save**

  <Callout type="info">
    The route pattern `yourdomain.com/analytics/*` ensures the worker only runs for analytics requests, not your entire site.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Add the script to your website:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Visit your site** with Developer Tools open
  2. **Check Network tab**:
     * Script loads from `/analytics/script.js`
     * Check response headers for `CF-Cache-Status` (HIT/MISS)
  3. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Cloudflare Workers intercept requests at the edge:

1. Request to `yourdomain.com/analytics/script.js` hits Cloudflare edge
2. Worker checks cache for GET requests
3. If not cached, proxies to `app.rybbit.io/api/script.js`
4. Response is cached at the edge location
5. Subsequent requests serve from edge cache (ultra-fast)

All tracking data flows through Cloudflare's network while preserving client IP information.

## Performance Benefits [#performance-benefits]

### Global Edge Network [#global-edge-network]

* **300+ locations worldwide**: Workers run in Cloudflare data centers globally
* **Sub-10ms cold start**: Faster than traditional serverless
* **Automatic scaling**: Handles traffic spikes without configuration

### Built-in Caching [#built-in-caching]

* **Cache API**: Leverages Cloudflare's massive edge cache
* **Intelligent caching**: Scripts cached at edge, tracking requests passed through
* **Instant cache purge**: Clear cache via Cloudflare API if needed

### Zero Infrastructure [#zero-infrastructure]

* **No servers to manage**: Fully serverless
* **Pay-per-request**: Free tier includes 100,000 requests/day
* **Automatic HTTPS**: Cloudflare handles SSL

## Advanced Configuration [#advanced-configuration]

### Cache Control [#cache-control]

Customize caching behavior:

```javascript
// Cache scripts for different durations
if (url.pathname === '/analytics/script.js') {
  cacheResponse.headers.set('Cache-Control', 'public, max-age=3600'); // 1 hour
} else if (url.pathname === '/analytics/replay.js') {
  cacheResponse.headers.set('Cache-Control', 'public, max-age=7200'); // 2 hours
}
```

### Rate Limiting [#rate-limiting]

Add basic rate limiting:

```javascript
// Simple in-memory rate limiting (per edge location)
const rateLimitMap = new Map();

async function checkRateLimit(ip) {
  const key = `ratelimit:${ip}`;
  const current = rateLimitMap.get(key) || { count: 0, resetAt: Date.now() + 60000 };

  if (Date.now() > current.resetAt) {
    current.count = 0;
    current.resetAt = Date.now() + 60000;
  }

  current.count++;
  rateLimitMap.set(key, current);

  return current.count > 100; // 100 requests per minute
}
```

### Logging and Analytics [#logging-and-analytics]

Log proxy usage:

```javascript
async function handleRequest(request) {
  const startTime = Date.now();

  try {
    const response = await proxyToRybbit(request, url);
    const duration = Date.now() - startTime;

    // Log to Cloudflare Analytics Engine (if enabled)
    console.log({
      path: url.pathname,
      status: response.status,
      duration,
      cached: response.headers.get('X-Cache-Status') === 'HIT',
    });

    return response;
  } catch (error) {
    console.error('Proxy error:', error);
    return new Response('Error', { status: 500 });
  }
}
```

## Cost Considerations [#cost-considerations]

Cloudflare Workers pricing (as of 2024):

* **Free tier**: 100,000 requests/day
* **Paid plan**: $5/month for 10 million requests + $0.50 per million after

For typical traffic:

* 100,000 sessions/month ≈ 200,000-500,000 requests (well within free tier)
* Even with session replay: Usually under 1 million requests/month

<Callout type="info">
  Most sites stay within the free tier. Bandwidth is unlimited on all Cloudflare plans.
</Callout>

## Troubleshooting [#troubleshooting]

### Worker not triggering [#worker-not-triggering]

**Problem**: Requests bypass worker.

**Solution**:

1. Verify route is configured: `yourdomain.com/analytics/*`
2. Check zone matches your domain
3. Ensure orange-cloud (proxy) is enabled on DNS record

### Cache not working [#cache-not-working]

**Problem**: `X-Cache-Status` always shows MISS.

**Solution**:

1. Verify cache key includes important parts:
   ```javascript
   const cacheKey = new Request(rybbitUrl, request);
   ```
2. Ensure `Cache-Control` headers are set
3. Check method is GET (POST requests aren't cached)

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show Cloudflare IPs.

**Solution**:
Use `CF-Connecting-IP` header:

```javascript
const clientIp = request.headers.get('CF-Connecting-IP');
proxyHeaders.set('X-Real-IP', clientIp);
```

### Deployment errors [#deployment-errors]

**Problem**: Worker fails to deploy.

**Solution**:

1. Check syntax in editor (no console.log in production)
2. Verify all async functions use await
3. Test locally with Wrangler:
   ```bash
   npm install -g wrangler
   wrangler dev
   ```

## Local Development [#local-development]

Use Wrangler for local testing:

```bash
# Install Wrangler
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Create worker
wrangler init rybbit-proxy

# Dev server
wrangler dev

# Deploy
wrangler deploy
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/) - Official docs
* [Workers Cache API](https://developers.cloudflare.com/workers/runtime-apis/cache/) - Caching documentation


# Express.js Proxy Setup (/docs/proxy-guide/express)





Express.js makes it easy to proxy Rybbit tracking using middleware. This guide shows how to set up a reverse proxy using `http-proxy-middleware`.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

The `http-proxy-middleware` package provides a simple way to proxy requests in Express applications, making it perfect for routing analytics requests to Rybbit servers.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your Express app
* Forward necessary headers for accurate tracking
* Optional caching for better performance
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Node.js and Express.js application
* npm or yarn package manager
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Install http-proxy-middleware [#install-http-proxy-middleware]

  Install the proxy middleware package:

  ```bash
  npm install http-proxy-middleware
  ```

  Or with yarn:

  ```bash
  yarn add http-proxy-middleware
  ```

  ### Configure Environment Variables [#configure-environment-variables]

  Create or update your `.env` file:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  <Callout type="info">
    Install `dotenv` if not already: `npm install dotenv`
  </Callout>

  ### Add Proxy Middleware to Express [#add-proxy-middleware-to-express]

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'TypeScript']">
    <Tab>
      Add to your Express server file (e.g., `server.js` or `app.js`):

      ```javascript
      // server.js
      require('dotenv').config();
      const express = require('express');
      const { createProxyMiddleware } = require('http-proxy-middleware');

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      // Rybbit Analytics Proxy
      // Proxy all /analytics/* requests to Rybbit
      app.use('/analytics', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api', // Rewrite /analytics/script.js to /api/script.js
        },
        onProxyReq: (proxyReq, req, res) => {
          // Forward client IP for accurate geolocation
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
        logLevel: 'warn',
      }));

      // Exception for site config endpoint (different path structure)
      app.use('/analytics/site/tracking-config', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics/site': '/api/site', // Rewrite to /api/site/tracking-config
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
      }));

      // Your other routes
      app.get('/', (req, res) => {
        res.send('Hello World');
      });

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>

    <Tab>
      Minimal setup with basic tracking:

      ```javascript
      // server.js
      require('dotenv').config();
      const express = require('express');
      const { createProxyMiddleware } = require('http-proxy-middleware');

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      // Proxy script and track endpoints only
      app.use(['/analytics/script.js', '/analytics/track'], createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api',
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
      }));

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>

    <Tab>
      For TypeScript projects:

      ```typescript
      // server.ts
      import 'dotenv/config';
      import express, { Request, Response } from 'express';
      import { createProxyMiddleware, Options } from 'http-proxy-middleware';

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      const proxyOptions: Options = {
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api',
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp as string);
          proxyReq.setHeader('X-Real-IP', clientIp as string);
        },
        logLevel: 'warn',
      };

      app.use('/analytics', createProxyMiddleware(proxyOptions));

      app.use('/analytics/site/tracking-config', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics/site': '/api/site',
        },
        onProxyReq: proxyOptions.onProxyReq,
      }));

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>
  </Tabs>

  ### Update Your Tracking Script [#update-your-tracking-script]

  In your HTML or template files:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Start Your Server [#start-your-server]

  ```bash
  node server.js
  ```

  Or with nodemon for development:

  ```bash
  npm install -D nodemon
  npx nodemon server.js
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Test script endpoint**:
     ```bash
     curl -I http://localhost:3000/analytics/script.js
     ```

  2. **Open your app** in a browser with Developer Tools

  3. **Check Network tab**: Requests should go to `/analytics/*`

  4. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

The `http-proxy-middleware` intercepts requests matching the specified paths and forwards them to Rybbit:

1. Request to `/analytics/script.js` is intercepted
2. Path is rewritten to `/api/script.js`
3. Request is forwarded to `https://app.rybbit.io/api/script.js`
4. Client IP headers are added for accurate tracking
5. Response is sent back to the browser

## Advanced Configuration [#advanced-configuration]

### Caching Responses [#caching-responses]

Add caching for better performance:

```javascript
const NodeCache = require('node-cache');
const cache = new NodeCache({ stdTTL: 3600 }); // 1 hour default

// Install: npm install node-cache

// Caching middleware for scripts
const cacheMiddleware = (req, res, next) => {
  const key = req.originalUrl;
  const cachedResponse = cache.get(key);

  if (cachedResponse) {
    res.set('X-Cache-Status', 'HIT');
    return res.send(cachedResponse);
  }

  // Store original send
  const originalSend = res.send.bind(res);
  res.send = (body) => {
    cache.set(key, body);
    res.set('X-Cache-Status', 'MISS');
    return originalSend(body);
  };
  next();
};

// Apply caching only to script files
app.use('/analytics/script.js', cacheMiddleware);
app.use('/analytics/script.js', createProxyMiddleware({
  // ... proxy config
}));
```

### Request Size Limits [#request-size-limits]

For session replay uploads, increase body size limit:

```javascript
const express = require('express');
const app = express();

// Increase limit for session replay endpoints
app.use('/analytics/session-replay', express.json({ limit: '10mb' }));
app.use('/analytics/session-replay', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  pathRewrite: {
    '^/analytics': '/api',
  },
}));
```

### Rate Limiting [#rate-limiting]

Protect your proxy with rate limiting:

```javascript
const rateLimit = require('express-rate-limit');

// Install: npm install express-rate-limit

const analyticsLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 100, // Limit each IP to 100 requests per minute
  message: 'Too many requests from this IP',
  standardHeaders: true,
  legacyHeaders: false,
});

// Apply to tracking endpoints
app.use('/analytics/track', analyticsLimiter);
app.use('/analytics/track', createProxyMiddleware({
  // ... proxy config
}));
```

### Error Handling [#error-handling]

Add error handling for proxy failures:

```javascript
app.use('/analytics', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  pathRewrite: {
    '^/analytics': '/api',
  },
  onError: (err, req, res) => {
    console.error('Proxy error:', err);
    res.status(500).json({ error: 'Analytics proxy error' });
  },
  onProxyReq: (proxyReq, req, res) => {
    const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
    proxyReq.setHeader('X-Forwarded-For', clientIp);
    proxyReq.setHeader('X-Real-IP', clientIp);
  },
}));
```

### CORS Configuration [#cors-configuration]

If serving API endpoints to other domains:

```javascript
const cors = require('cors');

// Install: npm install cors

app.use('/analytics', cors({
  origin: ['https://yourdomain.com', 'https://www.yourdomain.com'],
  credentials: true,
}));

app.use('/analytics', createProxyMiddleware({
  // ... proxy config
}));
```

## Troubleshooting [#troubleshooting]

### Requests timing out [#requests-timing-out]

**Problem**: Proxy requests hang or timeout.

**Solution**:
Increase timeout limits:

```javascript
app.use('/analytics', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  timeout: 30000, // 30 seconds
  proxyTimeout: 30000,
  pathRewrite: {
    '^/analytics': '/api',
  },
}));
```

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show server's location.

**Solution**:
Ensure IP forwarding is configured:

```javascript
onProxyReq: (proxyReq, req, res) => {
  const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  proxyReq.setHeader('X-Forwarded-For', clientIp);
  proxyReq.setHeader('X-Real-IP', clientIp);
}
```

### Path rewriting issues [#path-rewriting-issues]

**Problem**: 404 errors on Rybbit endpoints.

**Solution**:
Check path rewriting is correct:

```javascript
pathRewrite: {
  '^/analytics': '/api', // /analytics/script.js → /api/script.js
}
```

Debug by logging:

```javascript
onProxyReq: (proxyReq, req, res) => {
  console.log('Proxying:', req.method, req.path, '→', proxyReq.path);
}
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [http-proxy-middleware docs](https://github.com/chimurai/http-proxy-middleware) - Middleware documentation


# Generic Proxy Setup (/docs/proxy-guide/get-started)





This guide covers the core concepts for setting up a Rybbit proxy with any reverse proxy or server framework. If your specific framework has a dedicated guide, we recommend following that instead for optimized instructions.

## Prerequisites [#prerequisites]

Before setting up the proxy, ensure you have:

* **A domain or subdomain** where you'll serve the proxied scripts (e.g., `yourdomain.com` or `analytics.yourdomain.com`)
* **SSL/TLS certificate** for HTTPS (required for modern browsers)
* **Server or platform** with reverse proxy capabilities
* **Your Rybbit instance URL**:
  * Cloud: `https://app.rybbit.io`
  * Self-hosted: Your Rybbit instance URL (e.g., `https://analytics.yourcompany.com`)
* **Your Rybbit site ID** (found in your Rybbit dashboard)

## Understanding the Endpoints [#understanding-the-endpoints]

Rybbit uses several endpoints for tracking. You can choose between a minimal setup or full proxy:

<Tabs items="['Minimal Setup', 'Full Setup (Recommended)']">
  <Tab>
    **Required endpoints for basic tracking:**

    | Endpoint         | Method | Purpose                 | Cache    |
    | ---------------- | ------ | ----------------------- | -------- |
    | `/api/script.js` | GET    | Main tracking script    | 1 hour   |
    | `/api/track`     | POST   | Event tracking endpoint | No cache |

    This minimal setup enables basic pageview and event tracking, but won't support session replay or some advanced features.
  </Tab>

  <Tab>
    **All endpoints for complete functionality:**

    | Endpoint                             | Method | Purpose                         | Cache     |
    | ------------------------------------ | ------ | ------------------------------- | --------- |
    | `/api/script.js`                     | GET    | Main tracking script (minified) | 1 hour    |
    | `/api/replay.js`                     | GET    | Session replay recording script | 1 day     |
    | `/api/metrics.js`                    | GET    | Web Vitals metrics script       | 1 day     |
    | `/api/track`                         | POST   | Event tracking endpoint         | No cache  |
    | `/api/identify`                      | POST   | User identification endpoint    | No cache  |
    | `/api/session-replay/record/:siteId` | POST   | Session replay data upload      | No cache  |
    | `/api/site/tracking-config/:siteId`  | GET    | Site configuration              | 5 minutes |

    This setup supports all Rybbit features including session replay, Web Vitals, and custom events.
  </Tab>
</Tabs>

<Callout type="info">
  The session replay and metrics scripts (`/api/replay.js` and `/api/metrics.js`) are loaded dynamically by the main script when those features are enabled in your site settings. You don't need to include them in your HTML.
</Callout>

## Implementation Steps [#implementation-steps]

<Steps>
  ### Configure Your Proxy Rules [#configure-your-proxy-rules]

  Set up your reverse proxy to forward requests from your chosen path (e.g., `/analytics/*`) to the Rybbit server.

  **Generic proxy configuration pattern:**

  ```
  Your domain path          →  Rybbit backend
  -----------------            ---------------
  /analytics/script.js      →  https://app.rybbit.io/api/script.js
  /analytics/track          →  https://app.rybbit.io/api/track
  /analytics/replay.js      →  https://app.rybbit.io/api/replay.js
  ... and so on
  ```

  **Key requirements:**

  * Preserve the HTTP method (GET or POST)
  * Forward the browser's original request headers — pass through **all** incoming headers except `Host` and hop-by-hop headers (`Connection`, `Content-Length`), rather than hand-picking a few. See [Request Header Forwarding](#request-header-forwarding) for why this matters.
  * Maintain request/response body for POST requests
  * Set appropriate Content-Type headers
  * Forward the visitor IP in `X-Forwarded-For`
  * Enable the **First-Party Proxy** toggle for your site (see below)

  ### Enable First-Party Proxy in Site Settings [#enable-first-party-proxy-in-site-settings]

  In your Rybbit dashboard, open **Site Settings → Privacy & Security** and enable **First-Party Proxy**. This tells Rybbit that requests for this site arrive via your proxy, so the visitor IP in `X-Forwarded-For` is trusted directly instead of being inferred from network topology. Without it, Rybbit may attribute traffic to your proxy server's IP — producing wrong geolocation and merging all visitors into a few users.

  ### Configure Caching (Optional but Recommended) [#configure-caching-optional-but-recommended]

  Implement caching to reduce load on Rybbit servers and improve performance:

  **Recommended cache durations:**

  * **Scripts** (`.js` files): 1 hour (3600 seconds)
    * These change infrequently but may be updated for bug fixes
  * **Site configuration** (`/api/site/tracking-config/*`): 5 minutes (300 seconds)
    * Updated when you change settings in the dashboard
  * **Tracking endpoints** (POST requests): Never cache
    * Each request contains unique event data

  **Example cache headers to set:**

  ```
  Cache-Control: public, max-age=3600  # For scripts
  Cache-Control: public, max-age=300   # For config
  Cache-Control: no-store              # For tracking POSTs
  ```

  ### Update Your Tracking Script [#update-your-tracking-script]

  Change your script tag to load from your proxied domain instead of directly from Rybbit:

  **Before (direct loading):**

  ```html
  <script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  **After (proxied):**

  ```html
  <script src="https://yourdomain.com/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  <Callout type="info">
    **How Auto-Discovery Works**: The Rybbit script automatically extracts the analytics host from its own `src` attribute by splitting on `/script.js`. This means when it loads from `https://yourdomain.com/analytics/script.js`, it automatically sends all tracking data to `https://yourdomain.com/analytics/*` endpoints.
  </Callout>

  ### Verify the Setup [#verify-the-setup]

  Test your proxy configuration to ensure everything works correctly:

  1. **Open your website** in a browser with Developer Tools open
  2. **Go to the Network tab** and filter by "script" or your proxy path
  3. **Verify the script loads**:
     * You should see a request to `yourdomain.com/analytics/script.js`
     * Status should be `200 OK`
     * Content-Type should be `application/javascript`
  4. **Verify tracking works**:
     * Navigate to another page or trigger an event
     * You should see POST requests to `yourdomain.com/analytics/track`
     * Check the response is successful (200 OK)
  5. **Check your Rybbit dashboard**:
     * Wait 1-2 minutes for data to process
     * Verify your session appears in real-time dashboard

  ### Configure Security Headers (Optional) [#configure-security-headers-optional]

  Add security headers to protect your proxy:

  **Recommended headers:**

  ```
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  Referrer-Policy: strict-origin-when-cross-origin
  ```

  **CORS headers** (should be preserved from Rybbit):

  ```
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, OPTIONS
  Access-Control-Allow-Headers: Content-Type
  ```
</Steps>

## Request Header Forwarding [#request-header-forwarding]

Forward the browser's original headers to the Rybbit backend. The simplest and most robust approach is to pass through **every** incoming request header except `Host` and hop-by-hop headers (`Connection`, `Content-Length` — let your HTTP client recompute those).

Why this matters: Rybbit's bot detection scores requests on headers that every real browser sends. A proxy that forwards only `User-Agent` and the visitor IP produces requests that look exactly like a script — the events return `200 OK` but are classified as bot traffic and never appear in your dashboard.

If you must whitelist headers instead of passing everything through, this is the minimum set:

| Header                                                | Purpose                                            | Required    |
| ----------------------------------------------------- | -------------------------------------------------- | ----------- |
| `User-Agent`                                          | Device and browser detection                       | Yes         |
| `X-Forwarded-For`                                     | Visitor IP for geolocation and user identification | Yes         |
| `Accept-Language`                                     | Language detection, bot filtering                  | Yes         |
| `Accept`                                              | Bot filtering                                      | Yes         |
| `Accept-Encoding`                                     | Bot filtering (must include `gzip`)                | Yes         |
| `Sec-Fetch-Site`, `Sec-Fetch-Mode`, `Sec-Fetch-Dest`  | Bot filtering (sent by all Chromium browsers)      | Yes         |
| `Sec-CH-UA`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Platform` | Browser detection                                  | Recommended |
| `Referer`                                             | Referrer tracking                                  | Recommended |
| `Content-Type`                                        | POST body parsing                                  | Yes (POSTs) |

<Callout type="warn">
  **IP Forwarding**: Rybbit uses IP addresses for geolocation (country/city) and creating anonymous user identifiers (hashed IP + User Agent). If you don't forward the visitor IP in `X-Forwarded-For`, all traffic will appear to come from your proxy server's IP.
</Callout>

### Forwarded IP Headers [#forwarded-ip-headers]

Set `X-Forwarded-For` to the original visitor IP before forwarding the request to Rybbit, and enable the **First-Party Proxy** toggle in your site settings so Rybbit trusts it unconditionally.

<Callout type="warn">
  **Use `X-Forwarded-For`, not `X-Real-IP`.** On Rybbit Cloud, `X-Real-IP` is consumed by our edge network (Cloudflare treats it as an internal header) and never reaches the backend — a proxy that relies on it will silently fall back to the wrong IP. `X-Forwarded-For` passes through intact. Coincidentally, AWS CloudFront also cannot send `X-Real-IP` (it's on the [origin custom-header denylist](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html#add-origin-custom-headers-denylist)). Setting `X-Real-IP` as well does no harm on self-hosted instances, but never make it the only IP header.
</Callout>

**Cloudflare Worker example:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

const proxyHeaders = new Headers(request.headers);
proxyHeaders.set('X-Real-IP', clientIp);
proxyHeaders.set('X-Forwarded-For', clientIp);
```

**CloudFront example:**

* Set `X-Forwarded-For` to the viewer IP from a CloudFront Function/Lambda\@Edge (CloudFront cannot forward `X-Real-IP`)
* Forward `User-Agent`, `Referer`, and `Accept-Language`

```javascript
// CloudFront Function (viewer-request)
function handler(event) {
  event.request.headers["x-forwarded-for"] = { value: event.viewer.ip };
  return event.request;
}
```

## Bandwidth Considerations [#bandwidth-considerations]

Proxying adds bandwidth usage to your infrastructure. Here's what to expect:

**Typical bandwidth per session:**

* Initial script load: \~18 KB (one-time per session)
* Pageview tracking: \~0.5-2 KB per pageview
* Custom events: \~0.5-3 KB per event
* Session replay: 50-500 KB per session (if enabled, varies by session length)
* Web Vitals: \~1-2 KB per page

**Estimated monthly bandwidth** for a site with 100,000 monthly sessions:

* Without session replay: \~5-10 GB/month
* With session replay: \~30-80 GB/month

Most modern hosting plans can handle this easily, but verify your bandwidth limits if you have high traffic or session replay enabled.

## Performance Optimization [#performance-optimization]

### Use a CDN [#use-a-cdn]

If your server has CDN capabilities (like Cloudflare, Fastly, or AWS CloudFront), configure it to cache the static scripts:

* Cache scripts at edge locations worldwide
* Reduce latency for global users
* Offload bandwidth from your origin server

### Enable Compression [#enable-compression]

Ensure your proxy enables gzip or brotli compression:

```
Content-Encoding: gzip
```

This can reduce script size by 60-70%, improving load times and reducing bandwidth.

### Connection Reuse [#connection-reuse]

Configure your proxy to maintain persistent connections to Rybbit's backend to reduce latency on repeated requests.

## Common Proxy Patterns [#common-proxy-patterns]

<Tabs items="['Subdomain Proxy', 'Path-Based Proxy']">
  <Tab>
    Use a dedicated subdomain for analytics:

    ```
    https://analytics.yourdomain.com/script.js  →  https://app.rybbit.io/api/script.js
    https://analytics.yourdomain.com/track      →  https://app.rybbit.io/api/track
    ```

    **Pros:**

    * Clean separation of concerns
    * Easy to manage SSL certificate
    * Can use separate CDN configuration

    **Cons:**

    * Additional DNS lookup (minor performance impact)
    * Need to manage subdomain DNS
  </Tab>

  <Tab>
    Use a path on your main domain:

    ```
    https://yourdomain.com/analytics/script.js  →  https://app.rybbit.io/api/script.js
    https://yourdomain.com/analytics/track      →  https://app.rybbit.io/api/track
    ```

    **Pros:**

    * No additional DNS lookup
    * Single SSL certificate
    * Truly first-party from browser perspective

    **Cons:**

    * Must ensure proxy path doesn't conflict with your app routes
  </Tab>
</Tabs>

## Security Considerations [#security-considerations]

### Rate Limiting [#rate-limiting]

Consider adding rate limiting to prevent abuse:

* Limit POST requests to tracking endpoints (e.g., 100 requests per minute per IP)
* Whitelist your Rybbit backend IP if possible
* Monitor for unusual traffic patterns

### Request Size Limits [#request-size-limits]

Set appropriate request body size limits:

* `/api/track`, `/api/identify`: 1 MB max
* `/api/session-replay/record/*`: 10 MB max (session replay can send large payloads)

### HTTPS Only [#https-only]

Always serve your proxy over HTTPS:

* Modern browsers require HTTPS for many features
* Protects user data in transit
* Required for accurate tracking in secure contexts

## Troubleshooting [#troubleshooting]

If something isn't working, check:

1. **Script loads but no events tracked**: Verify all tracking endpoints (`/api/track`, etc.) are proxied
2. **CORS errors**: Ensure CORS headers are preserved from Rybbit backend
3. **404 errors**: Check that URL paths exactly match expected format
4. **Incorrect geolocation**: Verify `X-Forwarded-For` is set to the visitor IP and the **First-Party Proxy** toggle is enabled in site settings
5. **`/track` returns 200 but nothing appears in the dashboard**: Your proxy is probably forwarding too few headers and events are being classified as bot traffic — forward the full browser header set (see [Request Header Forwarding](#request-header-forwarding))
6. **Session replay not working**: Add `/api/replay.js` and `/api/session-replay/record/:siteId` endpoints

For more detailed troubleshooting, see our [troubleshooting guide](/docs/proxy-guide/troubleshooting).

## Next Steps [#next-steps]

Now that you understand the generic concepts, choose your specific framework or platform for detailed implementation instructions:

* [Next.js](/docs/proxy-guide/next-js)
* [Nginx](/docs/proxy-guide/nginx)
* [Caddy](/docs/proxy-guide/caddy)
* [Vercel](/docs/proxy-guide/vercel)
* [Express.js](/docs/proxy-guide/express)
* [Laravel](/docs/proxy-guide/laravel)
* [Astro](/docs/proxy-guide/astro)
* [Cloudflare Workers](/docs/proxy-guide/cloudflare-workers)


# Proxy Setup Guide (/docs/proxy-guide)





Proxying Rybbit's tracking script through your own domain helps bypass ad blockers and improves tracking accuracy by making all analytics requests appear as first-party traffic.

## What is Proxy Setup? [#what-is-proxy-setup]

When you add Rybbit's tracking script directly to your website using the default installation:

```html
<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
```

The browser loads the script from `app.rybbit.io`, which ad blockers can identify and block as third-party analytics. Even though Rybbit is privacy-focused and doesn't use cookies, some ad blockers use aggressive blocking rules that target any analytics domains.

**Proxying solves this** by serving the tracking script and handling tracking requests through your own domain (e.g., `yourdomain.com/analytics/script.js`), making all tracking appear as first-party traffic.

<Callout type="info">
  Rybbit is fully compliant with GDPR, CCPA, and other privacy regulations. It uses cookieless tracking based on IP + User Agent hashing with optional daily rotating salts. Proxying is about improving data accuracy, not circumventing privacy laws.
</Callout>

## Why Proxy Rybbit? [#why-proxy-rybbit]

### Improve Tracking Accuracy [#improve-tracking-accuracy]

Ad blockers are becoming increasingly aggressive and may block analytics scripts regardless of their privacy practices. By proxying through your own domain:

* **Bypass ad blocker detection**: Requests appear as first-party traffic to your own domain
* **Increase data completeness**: Typical improvement of 10-30% in tracked sessions
* **Maintain accurate metrics**: Get a true picture of your website's performance

### Stay Privacy-Compliant [#stay-privacy-compliant]

Proxying doesn't compromise user privacy:

* No cookies are used (Rybbit remains cookieless)
* User data is still processed according to your privacy policy
* GDPR, CCPA, and other privacy regulations remain fully satisfied
* Users can still opt out through browser settings or Do Not Track

### Better Performance (Optional) [#better-performance-optional]

With proper caching configuration, proxying can also improve performance:

* Serve scripts from your CDN or edge network
* Reduce DNS lookups (one less domain to resolve)
* Cache static scripts closer to your users

## How It Works [#how-it-works]

Here's the flow when you proxy Rybbit:

1. **User visits your website**: Your HTML includes the tracking script from your domain
   ```html
   <script src="https://yourdomain.com/analytics/script.js" data-site-id="123"></script>
   ```

2. **Script loads from your domain**: Your server proxies the request to Rybbit's servers
   * Request: `yourdomain.com/analytics/script.js` → proxied to → `app.rybbit.io/api/script.js`

3. **Script auto-discovers analytics host**: The Rybbit script automatically detects the domain it was loaded from
   ```typescript
   // The script extracts the host from its own src attribute
   const analyticsHost = src.split("/script.js")[0];
   // Result: "https://yourdomain.com/analytics"
   ```

4. **Tracking data sent through your domain**: All analytics events are sent to your domain and proxied to Rybbit
   * Event tracking: `yourdomain.com/analytics/track` → proxied to → `app.rybbit.io/api/track`
   * Session replay: `yourdomain.com/analytics/session-replay/record/{siteId}` → proxied
   * Configuration: `yourdomain.com/analytics/site/tracking-config/{siteId}` → proxied

5. **Data appears in your Rybbit dashboard**: No changes needed in the Rybbit interface

<Callout type="warn">
  **Bandwidth Consideration**: All tracking requests will flow through your server infrastructure, which will increase bandwidth usage. For most sites this is minimal (typically 10-50KB per session), but consider this when evaluating hosting costs.
</Callout>

## Choose Your Framework [#choose-your-framework]

Select the framework or platform that matches your setup:

<Cards>
  <Card icon="<SiNextdotjs />" title="Next.js" href="/docs/proxy-guide/next-js" className="flex items-center gap-2" />

  <Card icon="<SiNginx />" title="Nginx" href="/docs/proxy-guide/nginx" className="flex items-center gap-2" />

  <Card title="Caddy" href="/docs/proxy-guide/caddy" className="flex items-center gap-2" />

  <Card icon="<SiVercel />" title="Vercel" href="/docs/proxy-guide/vercel" className="flex items-center gap-2" />

  <Card icon="<SiExpress />" title="Express.js" href="/docs/proxy-guide/express" className="flex items-center gap-2" />

  <Card icon="<SiLaravel />" title="Laravel" href="/docs/proxy-guide/laravel" className="flex items-center gap-2" />

  <Card icon="<SiAstro />" title="Astro" href="/docs/proxy-guide/astro" className="flex items-center gap-2" />

  <Card icon="<SiCloudflare />" title="Cloudflare Workers" href="/docs/proxy-guide/cloudflare-workers" className="flex items-center gap-2" />
</Cards>

## Generic Implementation [#generic-implementation]

If your framework isn't listed above, check out our [generic implementation guide](/docs/proxy-guide/get-started) that covers the core concepts applicable to any reverse proxy or server setup.

## Need Help? [#need-help]

If you encounter issues during setup, check our [troubleshooting guide](/docs/proxy-guide/troubleshooting) for common problems and solutions.


# Laravel Proxy Setup (/docs/proxy-guide/laravel)





Laravel makes it straightforward to proxy Rybbit tracking using routes and the HTTP client. This guide shows how to set up proxy endpoints in your Laravel application.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Laravel's HTTP client (built on Guzzle) provides an elegant way to proxy requests to Rybbit servers while maintaining full control over headers, caching, and error handling.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your Laravel app
* Forward necessary headers for accurate tracking
* Optional caching with Laravel Cache
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Laravel 8 or later
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Configure Environment Variables [#configure-environment-variables]

  Add your Rybbit host to `.env`:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  ### Create Analytics Controller [#create-analytics-controller]

  Generate a controller for handling analytics proxying:

  ```bash
  php artisan make:controller AnalyticsProxyController
  ```

  Then implement the proxy logic:

  ```php
  <?php
  // app/Http/Controllers/AnalyticsProxyController.php

  namespace App\Http\Controllers;

  use Illuminate\Http\Request;
  use Illuminate\Support\Facades\Http;
  use Illuminate\Support\Facades\Cache;

  class AnalyticsProxyController extends Controller
  {
      private string $rybbitHost;

      public function __construct()
      {
          $this->rybbitHost = config('services.rybbit.host', 'https://app.rybbit.io');
      }

      /**
       * Proxy script requests (GET)
       */
      public function proxyScript(Request $request, string $script)
      {
          // Cache scripts for 1 hour
          $cacheKey = "rybbit_script_{$script}";

          return Cache::remember($cacheKey, 3600, function () use ($script, $request) {
              return $this->forwardRequest("api/{$script}", 'GET', $request);
          });
      }

      /**
       * Proxy tracking requests (POST)
       */
      public function proxyTrack(Request $request)
      {
          return $this->forwardRequest('api/track', 'POST', $request);
      }

      /**
       * Proxy identify requests (POST)
       */
      public function proxyIdentify(Request $request)
      {
          return $this->forwardRequest('api/identify', 'POST', $request);
      }

      /**
       * Proxy session replay recording (POST)
       */
      public function proxySessionReplay(Request $request, string $siteId)
      {
          return $this->forwardRequest("api/session-replay/record/{$siteId}", 'POST', $request);
      }

      /**
       * Proxy site configuration (GET)
       */
      public function proxySiteConfig(Request $request, string $siteId)
      {
          // Cache config for 5 minutes
          $cacheKey = "rybbit_config_{$siteId}";

          return Cache::remember($cacheKey, 300, function () use ($siteId, $request) {
              return $this->forwardRequest("api/site/tracking-config/{$siteId}", 'GET', $request);
          });
      }

      /**
       * Forward request to Rybbit backend
       */
      private function forwardRequest(string $path, string $method, Request $request)
      {
          $url = "{$this->rybbitHost}/{$path}";

          // Get client IP
          $clientIp = $request->header('X-Forwarded-For', $request->ip());

          // Build HTTP request
          $httpRequest = Http::timeout(30)
              ->withHeaders([
                  'X-Real-IP' => $clientIp,
                  'X-Forwarded-For' => $clientIp,
                  'User-Agent' => $request->header('User-Agent'),
                  'Referer' => $request->header('Referer', ''),
              ]);

          try {
              if ($method === 'POST') {
                  $response = $httpRequest->post($url, $request->all());
              } else {
                  $response = $httpRequest->get($url);
              }

              return response($response->body(), $response->status())
                  ->header('Content-Type', $response->header('Content-Type'));
          } catch (\Exception $e) {
              \Log::error('Rybbit proxy error', [
                  'url' => $url,
                  'error' => $e->getMessage(),
              ]);

              return response()->json(['error' => 'Analytics proxy error'], 500);
          }
      }
  }
  ```

  ### Add Routes [#add-routes]

  Add routes for the analytics proxy in `routes/web.php`:

  ```php
  <?php
  // routes/web.php

  use App\Http\Controllers\AnalyticsProxyController;

  // Analytics proxy routes
  Route::prefix('analytics')->group(function () {
      // Scripts (GET)
      Route::get('/{script}', [AnalyticsProxyController::class, 'proxyScript'])
          ->where('script', '(script|replay|metrics)\.js');

      // Tracking endpoints (POST)
      Route::post('/track', [AnalyticsProxyController::class, 'proxyTrack']);
      Route::post('/identify', [AnalyticsProxyController::class, 'proxyIdentify']);
      Route::post('/session-replay/record/{siteId}', [AnalyticsProxyController::class, 'proxySessionReplay']);

      // Configuration (GET)
      Route::get('/site/tracking-config/{siteId}', [AnalyticsProxyController::class, 'proxySiteConfig']);
  });
  ```

  ### Add Service Configuration (Optional) [#add-service-configuration-optional]

  Add Rybbit configuration to `config/services.php`:

  ```php
  <?php
  // config/services.php

  return [
      // ... other services

      'rybbit' => [
          'host' => env('RYBBIT_HOST', 'https://app.rybbit.io'),
      ],
  ];
  ```

  ### Update Your Blade Templates [#update-your-blade-templates]

  Add the tracking script to your layout:

  ```blade
  {{-- resources/views/layouts/app.blade.php --}}
  <!DOCTYPE html>
  <html lang="en">
  <head>
      <meta charset="UTF-8">
      <title>{{ config('app.name') }}</title>

      {{-- Rybbit Analytics --}}
      <script src="{{ url('/analytics/script.js') }}" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      @yield('content')
  </body>
  </html>
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Clear route cache** (if caching enabled):
     ```bash
     php artisan route:clear
     ```

  2. **Visit your application** with Developer Tools open

  3. **Check Network tab**: Requests should go to `/analytics/*`

  4. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Laravel routes intercept requests to `/analytics/*` and forward them to Rybbit:

1. Request to `/analytics/script.js` hits Laravel route
2. Controller forwards to `https://app.rybbit.io/api/script.js`
3. Response is cached (for cacheable endpoints)
4. Client IP and headers are preserved for accurate tracking

## Advanced Configuration [#advanced-configuration]

### Middleware for Rate Limiting [#middleware-for-rate-limiting]

Create rate limiting middleware:

```bash
php artisan make:middleware RateLimitAnalytics
```

```php
<?php
// app/Http/Middleware/RateLimitAnalytics.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Cache\RateLimiter;

class RateLimitAnalytics
{
    protected $limiter;

    public function __construct(RateLimiter $limiter)
    {
        $this->limiter = $limiter;
    }

    public function handle($request, Closure $next)
    {
        $key = 'analytics:' . $request->ip();

        if ($this->limiter->tooManyAttempts($key, 100)) {
            return response('Too Many Requests', 429);
        }

        $this->limiter->hit($key, 60); // 100 requests per minute

        return $next($request);
    }
}
```

Register in `app/Http/Kernel.php`:

```php
protected $routeMiddleware = [
    // ... other middleware
    'rate.limit.analytics' => \App\Http\Middleware\RateLimitAnalytics::class,
];
```

Apply to routes:

```php
Route::prefix('analytics')->middleware('rate.limit.analytics')->group(function () {
    // ... routes
});
```

### Custom Cache Configuration [#custom-cache-configuration]

Use different cache drivers for analytics:

```php
private function forwardRequest(string $path, string $method, Request $request)
{
    // Use Redis for analytics caching
    $cache = Cache::store('redis');

    // Or use file cache
    // $cache = Cache::store('file');

    // ... rest of the method
}
```

### Queue Large Requests [#queue-large-requests]

For large session replay uploads, use queues:

```bash
php artisan make:job ForwardAnalyticsData
```

```php
<?php
// app/Jobs/ForwardAnalyticsData.php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Http;

class ForwardAnalyticsData implements ShouldQueue
{
    use Queueable;

    protected $url;
    protected $data;
    protected $headers;

    public function __construct(string $url, array $data, array $headers)
    {
        $this->url = $url;
        $this->data = $data;
        $this->headers = $headers;
    }

    public function handle()
    {
        Http::withHeaders($this->headers)
            ->post($this->url, $this->data);
    }
}
```

Use in controller for session replay:

```php
public function proxySessionReplay(Request $request, string $siteId)
{
    // Dispatch job for async processing
    ForwardAnalyticsData::dispatch(
        "{$this->rybbitHost}/api/session-replay/record/{$siteId}",
        $request->all(),
        [
            'X-Real-IP' => $request->ip(),
            'User-Agent' => $request->header('User-Agent'),
        ]
    );

    return response()->json(['status' => 'queued']);
}
```

### CORS Configuration [#cors-configuration]

If serving from a different domain:

```php
<?php
// config/cors.php

return [
    'paths' => ['analytics/*'],
    'allowed_methods' => ['GET', 'POST'],
    'allowed_origins' => ['https://yourdomain.com'],
    'allowed_headers' => ['Content-Type', 'X-Requested-With'],
];
```

## Troubleshooting [#troubleshooting]

### 404 Not Found [#404-not-found]

**Problem**: Routes return 404.

**Solution**:

1. Clear route cache: `php artisan route:clear`
2. List routes to verify: `php artisan route:list --path=analytics`
3. Check route order (more specific routes first)

### Session errors with POST requests [#session-errors-with-post-requests]

**Problem**: CSRF token errors on tracking endpoints.

**Solution**:
Exclude analytics routes from CSRF protection in `app/Http/Middleware/VerifyCsrfToken.php`:

```php
protected $except = [
    'analytics/*',
];
```

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show server's location.

**Solution**:
Ensure IP forwarding in controller:

```php
$clientIp = $request->header('X-Forwarded-For', $request->ip());
```

And add to HTTP request:

```php
'X-Real-IP' => $clientIp,
'X-Forwarded-For' => $clientIp,
```

### Cache not clearing [#cache-not-clearing]

**Problem**: Old script cached after Rybbit update.

**Solution**:
Clear specific cache key:

```bash
php artisan cache:forget rybbit_script_script.js
```

Or clear all cache:

```bash
php artisan cache:clear
```

## Performance Optimization [#performance-optimization]

### Cache Optimization [#cache-optimization]

```php
// Configure cache tags for easy clearing
Cache::tags(['rybbit', 'scripts'])->remember($cacheKey, 3600, function () {
    // ... fetch script
});

// Clear all Rybbit cache
Cache::tags(['rybbit'])->flush();
```

### HTTP Client Optimization [#http-client-optimization]

```php
// Use connection pooling
Http::pool(fn (Pool $pool) => [
    $pool->get("{$this->rybbitHost}/api/script.js"),
    $pool->get("{$this->rybbitHost}/api/replay.js"),
]);
```

## Related Resources [#related-resources]

* [Laravel Integration Guide](/docs/guides/laravel) - General Laravel integration
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Laravel HTTP Client](https://laravel.com/docs/http-client) - Official Laravel docs


# Next.js Proxy Setup (/docs/proxy-guide/next-js)





Next.js provides a powerful [rewrites](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) feature that makes it easy to proxy Rybbit tracking through your own domain. This guide works with both the App Router (Next.js 13+) and Pages Router.

<Callout type="info">
  Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**. Rewrites on this platform automatically forward the browser's headers and set `X-Forwarded-For` to the visitor IP — the toggle tells Rybbit to trust that forwarded IP directly.
</Callout>

## Overview [#overview]

Next.js rewrites allow you to map incoming request paths to different destination URLs transparently. This is perfect for proxying analytics since the browser sees requests to your domain while Next.js forwards them to Rybbit's servers behind the scenes.

**What you'll achieve:**

* Serve Rybbit scripts from your domain (e.g., `/analytics/script.js`)
* Proxy all tracking requests through your Next.js application
* Bypass ad blocker detection with first-party requests
* Support all Rybbit features (session replay, Web Vitals, custom events)

## Prerequisites [#prerequisites]

* Next.js 12 or later (rewrites are supported in all modern versions)
* Your Rybbit site ID (found in your dashboard)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL (e.g., `https://analytics.yourcompany.com`)

## Implementation [#implementation]

<Steps>
  ### Configure Environment Variables [#configure-environment-variables]

  Create or update your `.env` or `.env.local` file with your Rybbit instance URL:

  <Tabs items="['Cloud Hosted', 'Self-Hosted']">
    <Tab>
      ```bash
      # .env.local
      NEXT_PUBLIC_RYBBIT_HOST=https://app.rybbit.io
      ```
    </Tab>

    <Tab>
      ```bash
      # .env.local
      NEXT_PUBLIC_RYBBIT_HOST=https://analytics.yourcompany.com
      ```

      Replace `analytics.yourcompany.com` with your actual Rybbit instance domain.
    </Tab>
  </Tabs>

  <Callout type="info">
    The `NEXT_PUBLIC_` prefix makes this environment variable available in both server and client environments, though it's primarily used during build time for the rewrites configuration.
  </Callout>

  ### Set Up Rewrites in next.config.js [#set-up-rewrites-in-nextconfigjs]

  Add or update the `rewrites` function in your `next.config.js` (or `next.config.mjs` for ESM):

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'ESM (next.config.mjs)']">
    <Tab>
      This configuration proxies all Rybbit endpoints including session replay and Web Vitals:

      ```javascript
      // next.config.js
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            // Tracking scripts
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/replay.js',
              destination: `${rybbitHost}/api/replay.js`,
            },
            {
              source: '/analytics/metrics.js',
              destination: `${rybbitHost}/api/metrics.js`,
            },
            // Tracking endpoints
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
            {
              source: '/analytics/identify',
              destination: `${rybbitHost}/api/identify`,
            },
            {
              source: '/analytics/session-replay/record/:siteId',
              destination: `${rybbitHost}/api/session-replay/record/:siteId`,
            },
            {
              source: '/analytics/site/tracking-config/:siteId',
              destination: `${rybbitHost}/api/site/tracking-config/:siteId`,
            },
          ];
        },
      };

      module.exports = nextConfig;
      ```
    </Tab>

    <Tab>
      Minimal setup with just script loading and basic event tracking:

      ```javascript
      // next.config.js
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
          ];
        },
      };

      module.exports = nextConfig;
      ```

      <Callout type="warn">
        This minimal setup won't support session replay or Web Vitals. Use the full proxy configuration if you need these features.
      </Callout>
    </Tab>

    <Tab>
      If you're using ES modules:

      ```javascript
      // next.config.mjs
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
            {
              source: '/analytics/replay.js',
              destination: `${rybbitHost}/api/replay.js`,
            },
            {
              source: '/analytics/metrics.js',
              destination: `${rybbitHost}/api/metrics.js`,
            },
            {
              source: '/analytics/identify',
              destination: `${rybbitHost}/api/identify`,
            },
            {
              source: '/analytics/session-replay/record/:siteId',
              destination: `${rybbitHost}/api/session-replay/record/:siteId`,
            },
            {
              source: '/analytics/site/tracking-config/:siteId',
              destination: `${rybbitHost}/api/site/tracking-config/:siteId`,
            },
          ];
        },
      };

      export default nextConfig;
      ```
    </Tab>
  </Tabs>

  <Callout type="info">
    **Custom Path**: You can change `/analytics` to any path you prefer (e.g., `/tracking`, `/stats`, `/rybbit`). Just ensure you use the same path consistently in both your rewrites and script tag.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your script tag to load from the proxied path instead of directly from Rybbit:

  <Tabs items="['App Router (Next.js 13+)', 'Pages Router', 'JavaScript (No TypeScript)']">
    <Tab>
      Update your root layout file:

      ```tsx
      // app/layout.tsx
      import Script from 'next/script';

      export default function RootLayout({
        children,
      }: {
        children: React.ReactNode;
      }) {
        return (
          <html lang="en">
            <body>
              {children}
              <Script
                src="/analytics/script.js"
                data-site-id="YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </body>
          </html>
        );
      }
      ```

      Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.
    </Tab>

    <Tab>
      Update your `_app.tsx` or `_app.jsx` file:

      ```tsx
      // pages/_app.tsx
      import Script from 'next/script';
      import type { AppProps } from 'next/app';

      function MyApp({ Component, pageProps }: AppProps) {
        return (
          <>
            <Component {...pageProps} />
            <Script
              src="/analytics/script.js"
              data-site-id="YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </>
        );
      }

      export default MyApp;
      ```

      Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.
    </Tab>

    <Tab>
      ```jsx
      // app/layout.js or pages/_app.js
      import Script from 'next/script';

      export default function RootLayout({ children }) {
        return (
          <html lang="en">
            <body>
              {children}
              <Script
                src="/analytics/script.js"
                data-site-id="YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </body>
          </html>
        );
      }
      ```
    </Tab>
  </Tabs>

  ### Restart Your Development Server [#restart-your-development-server]

  After updating `next.config.js`, restart your Next.js development server for the changes to take effect:

  ```bash
  # Stop the server (Ctrl+C) and restart
  npm run dev
  # or
  yarn dev
  # or
  pnpm dev
  ```

  ### Verify the Setup [#verify-the-setup]

  Open your website in a browser with Developer Tools:

  1. **Open the Network tab** and filter by "analytics" or "script"
  2. **Verify the script loads**:
     * You should see a request to `/analytics/script.js` (not `app.rybbit.io`)
     * Status should be `200 OK`
     * The domain should be your own domain
  3. **Verify tracking works**:
     * Navigate to another page or trigger an event
     * You should see POST requests to `/analytics/track`
     * All requests should show your domain, not `app.rybbit.io`
  4. **Check the Rybbit dashboard**:
     * Wait 1-2 minutes for data processing
     * Verify your session appears in the real-time dashboard
</Steps>

## How It Works [#how-it-works]

The Rybbit tracking script has a built-in auto-discovery mechanism. When it loads from:

```html
<script src="/analytics/script.js" data-site-id="123"></script>
```

It automatically extracts the analytics host from its own `src` attribute:

```typescript
// Inside Rybbit's script
const scriptElement = document.currentScript;
const src = scriptElement.getAttribute('src');
const analyticsHost = src.split('/script.js')[0];
// Result: "" (empty string means same domain)
```

This means all tracking requests automatically go to `/analytics/track`, `/analytics/identify`, etc., which Next.js then rewrites to forward to Rybbit's servers.

## Performance Considerations [#performance-considerations]

### Bandwidth Usage [#bandwidth-usage]

All tracking requests now flow through your Next.js server, which will increase bandwidth usage:

<Callout type="warn">
  **Bandwidth Impact**: Each session typically uses 10-50 KB without session replay, or 50-500 KB with session replay enabled. For a site with 100,000 monthly sessions, expect 5-10 GB/month additional bandwidth without replay, or 30-80 GB/month with replay.
</Callout>

Most Vercel, Netlify, or other hosting plans can handle this, but check your plan's bandwidth limits if you have high traffic.

### Caching [#caching]

Next.js automatically caches responses when possible, but you can optimize further:

**Using Vercel Edge Network:**
If deployed on Vercel, your rewrites benefit from the global Edge Network, which caches static scripts close to users worldwide.

**Custom caching headers:**
The Rybbit server sets cache headers on its scripts, which Next.js respects:

* Scripts (`.js` files): Cached for 1 hour (`script.js`) to 1 day (`replay.js`, `metrics.js`)
* Configuration: Not cached by the server (you may cache it for \~5 minutes at your proxy if desired)
* Tracking POSTs: Not cached

### Server Load [#server-load]

Rewrites are handled at the edge on Vercel, so there's minimal impact on your serverless functions. For self-hosted Next.js, consider:

* Using a CDN (Cloudflare, CloudFront, etc.) in front of Next.js
* Scaling your server if you have very high traffic
* Monitoring server response times

## Troubleshooting [#troubleshooting]

### Script loads but events aren't tracked [#script-loads-but-events-arent-tracked]

**Problem**: You see the script load successfully, but no tracking data appears in the dashboard.

**Solution**:

1. Check that `/analytics/track` is included in your rewrites
2. Verify POST requests to `/analytics/track` return `200 OK` in Network tab
3. Check for CORS errors in the browser console
4. Ensure your Rybbit instance URL is correct in `.env.local`

### 404 errors on tracking endpoints [#404-errors-on-tracking-endpoints]

**Problem**: Script loads fine, but tracking requests return 404.

**Solution**:

1. Verify all tracking endpoints are in your `rewrites()` configuration
2. Restart your dev server after changing `next.config.js`
3. Clear your browser cache
4. Check that the endpoint paths exactly match (case-sensitive)

### Session replay not working [#session-replay-not-working]

**Problem**: Basic tracking works but session replay doesn't record.

**Solution**:
Add the session replay endpoints to your rewrites:

```javascript
{
  source: '/analytics/replay.js',
  destination: `${rybbitHost}/api/replay.js`,
},
{
  source: '/analytics/session-replay/record/:siteId',
  destination: `${rybbitHost}/api/session-replay/record/:siteId`,
},
```

### Environment variable not loading [#environment-variable-not-loading]

**Problem**: Rewrites don't work, console shows warning about missing `NEXT_PUBLIC_RYBBIT_HOST`.

**Solution**:

1. Ensure you created `.env.local` in your project root
2. Restart your dev server after creating `.env.local`
3. For production, ensure environment variables are set in your hosting platform (Vercel, Netlify, etc.)

## Deployment Considerations [#deployment-considerations]

### Vercel [#vercel]

When deploying to Vercel:

1. Add `NEXT_PUBLIC_RYBBIT_HOST` environment variable in your Vercel project settings
2. Rewrites automatically work at the edge with zero configuration
3. Bandwidth is generous on all Vercel plans

### Self-Hosted [#self-hosted]

When self-hosting Next.js:

1. Ensure environment variables are available to the Next.js process
2. Consider adding a CDN layer for better caching and reduced bandwidth
3. Monitor server load if you have high traffic

### Other Platforms (Netlify, AWS, etc.) [#other-platforms-netlify-aws-etc]

1. Set environment variables in your platform's settings
2. Verify rewrites are supported (most platforms support Next.js rewrites)
3. Check bandwidth limits for your plan

## Advanced Configuration [#advanced-configuration]

### Different paths for different environments [#different-paths-for-different-environments]

You can customize the proxy path based on the environment:

```javascript
// next.config.js
const nextConfig = {
  async rewrites() {
    const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;
    const analyticsPath = process.env.NODE_ENV === 'development'
      ? '/dev-analytics'
      : '/analytics';

    return [
      {
        source: `${analyticsPath}/script.js`,
        destination: `${rybbitHost}/api/script.js`,
      },
      // ... other rewrites
    ];
  },
};
```

### Conditional proxy (development only) [#conditional-proxy-development-only]

If you only want proxying in production:

```javascript
// next.config.js
const nextConfig = {
  async rewrites() {
    if (process.env.NODE_ENV === 'development') {
      return []; // No proxy in development
    }

    // ... production rewrites
  },
};
```

## Related Resources [#related-resources]

* [Next.js Integration Guide](/docs/guides/react/next-js) - General Next.js integration
* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Custom Events](/docs/track-events) - Track custom events
* [Next.js Rewrites Documentation](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) - Official Next.js docs


# Nginx Proxy Setup (/docs/proxy-guide/nginx)





Nginx is a powerful web server and reverse proxy that makes it easy to proxy Rybbit tracking through your own domain. This guide shows how to configure Nginx to forward tracking requests to Rybbit servers while caching static scripts for better performance.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Nginx's `proxy_pass` directive lets you forward requests from your domain to Rybbit's servers. Combined with caching, this provides excellent performance and reliability for proxying analytics.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your domain
* Cache static scripts for better performance
* Forward necessary headers for accurate tracking
* Support all Rybbit features (session replay, Web Vitals, custom events)

## Prerequisites [#prerequisites]

* Nginx installed (version 1.18 or later recommended)
* SSL/TLS certificate configured (Let's Encrypt recommended)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID (found in your dashboard)

## Implementation [#implementation]

<Steps>
  ### Configure Nginx Proxy [#configure-nginx-proxy]

  Add a new location block (or update existing configuration) in your Nginx site configuration:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'With Cache Zone']">
    <Tab>
      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          listen 443 ssl http2;
          server_name yourdomain.com;

          # Your SSL configuration
          ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
          ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

          # Your main site configuration
          location / {
              # Your regular site config...
          }

          # Rybbit Analytics Proxy
          # Main tracking script (cached)
          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              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;

              # Cache for 1 hour
              proxy_cache_valid 200 1h;
              proxy_cache_bypass $http_cache_control;
              add_header X-Cache-Status $upstream_cache_status;
          }

          # Session replay script (cached)
          location = /analytics/replay.js {
              proxy_pass https://app.rybbit.io/api/replay.js;
              proxy_set_header Host app.rybbit.io;
              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;

              proxy_cache_valid 200 1h;
          }

          # Web Vitals metrics script (cached)
          location = /analytics/metrics.js {
              proxy_pass https://app.rybbit.io/api/metrics.js;
              proxy_set_header Host app.rybbit.io;
              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;

              proxy_cache_valid 200 1h;
          }

          # Event tracking endpoint (not cached)
          location = /analytics/track {
              proxy_pass https://app.rybbit.io/api/track;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;
          }

          # User identification endpoint (not cached)
          location = /analytics/identify {
              proxy_pass https://app.rybbit.io/api/identify;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;
          }

          # Session replay recording endpoint (not cached)
          location ~ ^/analytics/session-replay/record/(.*)$ {
              proxy_pass https://app.rybbit.io/api/session-replay/record/$1;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;

              # Allow larger uploads for session replay
              client_max_body_size 10M;
          }

          # Site configuration endpoint (cached briefly)
          location ~ ^/analytics/site/tracking-config/(.*)$ {
              proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
              proxy_set_header Host app.rybbit.io;
              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;

              # Cache for 5 minutes
              proxy_cache_valid 200 5m;
          }
      }
      ```

      <Callout type="info">
        Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
      </Callout>
    </Tab>

    <Tab>
      Minimal configuration for basic tracking:

      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          listen 443 ssl http2;
          server_name yourdomain.com;

          # SSL configuration
          ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
          ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

          # Main tracking script
          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;

              proxy_cache_valid 200 1h;
          }

          # Event tracking
          location = /analytics/track {
              proxy_pass https://app.rybbit.io/api/track;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;
          }
      }
      ```
    </Tab>

    <Tab>
      For better performance with caching, define a cache zone:

      ```nginx
      # /etc/nginx/nginx.conf (http block)
      http {
          # Define cache zone for Rybbit
          proxy_cache_path /var/cache/nginx/rybbit
              levels=1:2
              keys_zone=rybbit_cache:10m
              max_size=100m
              inactive=60m
              use_temp_path=off;

          # ... rest of http config
      }
      ```

      Then in your site config:

      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          # ... server config

          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;

              # Use the cache zone
              proxy_cache rybbit_cache;
              proxy_cache_valid 200 1h;
              proxy_cache_key "$scheme$request_method$host$request_uri";
              add_header X-Cache-Status $upstream_cache_status;
          }

          # ... other locations
      }
      ```
    </Tab>
  </Tabs>

  <Callout type="warn">
    **Important**: The `proxy_set_header X-Real-IP` and `X-Forwarded-For` headers are critical for accurate geolocation and user identification. Without these, all traffic will appear to come from your Nginx server's IP.
  </Callout>

  ### Create Cache Directory (Optional) [#create-cache-directory-optional]

  If using a cache zone, create the cache directory:

  ```bash
  sudo mkdir -p /var/cache/nginx/rybbit
  sudo chown www-data:www-data /var/cache/nginx/rybbit
  ```

  ### Test Nginx Configuration [#test-nginx-configuration]

  Before reloading Nginx, test the configuration for syntax errors:

  ```bash
  sudo nginx -t
  ```

  You should see:

  ```
  nginx: configuration file /etc/nginx/nginx.conf test is successful
  ```

  ### Reload Nginx [#reload-nginx]

  Apply the changes by reloading Nginx:

  ```bash
  sudo systemctl reload nginx
  ```

  Or if you prefer:

  ```bash
  sudo nginx -s reload
  ```

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to load the script from your proxied domain:

  ```html
  <!DOCTYPE html>
  <html>
  <head>
      <!-- ... other head elements -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      <!-- Your content -->
  </body>
  </html>
  ```

  Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.

  ### Verify the Setup [#verify-the-setup]

  Test your configuration:

  1. **Check Nginx is running**:
     ```bash
     sudo systemctl status nginx
     ```

  2. **Test script loading**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see:

     ```
     HTTP/2 200
     content-type: application/javascript
     x-cache-status: MISS  # First request
     ```

  3. **Test again to verify caching**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see:

     ```
     HTTP/2 200
     x-cache-status: HIT  # Cached!
     ```

  4. **Open your website** in a browser with Developer Tools and verify:
     * Script loads from `/analytics/script.js` (your domain)
     * Tracking requests go to `/analytics/track` (your domain)
     * Data appears in your Rybbit dashboard after 1-2 minutes
</Steps>

## How It Works [#how-it-works]

Nginx's `proxy_pass` directive transparently forwards requests to Rybbit's servers:

1. Browser requests `https://yourdomain.com/analytics/script.js`
2. Nginx matches the location block and forwards to `https://app.rybbit.io/api/script.js`
3. Nginx sets necessary headers (`X-Real-IP`, `X-Forwarded-For`) for accurate tracking
4. Response is cached (if configured) and sent back to browser
5. All subsequent tracking requests follow the same pattern

The Rybbit script auto-detects it's being served from your domain and sends all tracking data to your domain's `/analytics/*` endpoints.

## Performance Optimization [#performance-optimization]

### Caching Strategy [#caching-strategy]

Configure different cache durations based on content type:

```nginx
# Scripts - cache for 1 hour
location ~ ^/analytics/(script|replay|metrics)\.js$ {
    proxy_pass https://app.rybbit.io/api/$1.js;
    # ... proxy headers
    proxy_cache_valid 200 1h;
    proxy_cache_valid 404 1m;  # Cache 404s briefly
}

# Config - cache for 5 minutes (changes when you update dashboard settings)
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
    # ... proxy headers
    proxy_cache_valid 200 5m;
}

# Tracking - never cache (each request is unique)
location ~ ^/analytics/(track|identify)$ {
    proxy_pass https://app.rybbit.io/api/$1;
    # ... proxy headers
    # No caching directives
}
```

### Gzip Compression [#gzip-compression]

Enable compression for JavaScript files:

```nginx
# In http or server block
gzip on;
gzip_vary on;
gzip_types application/javascript text/javascript;
gzip_min_length 1000;
```

### Connection Pooling [#connection-pooling]

Keep connections to Rybbit backend alive for better performance:

```nginx
upstream rybbit_backend {
    server app.rybbit.io:443;
    keepalive 32;
}

location /analytics/ {
    proxy_pass https://rybbit_backend/api/;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    # ... other proxy headers
}
```

### Proxy Buffering [#proxy-buffering]

For better performance with larger session replay uploads:

```nginx
location ~ ^/analytics/session-replay/record/ {
    proxy_pass https://app.rybbit.io/api/session-replay/record/;
    # ... proxy headers

    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;
    proxy_busy_buffers_size 8k;
    client_max_body_size 10M;
}
```

## Security Considerations [#security-considerations]

### Rate Limiting [#rate-limiting]

Protect your proxy from abuse with rate limiting:

```nginx
# In http block
http {
    limit_req_zone $binary_remote_addr zone=analytics_limit:10m rate=10r/s;

    # ... rest of config
}

# In server block
location = /analytics/track {
    limit_req zone=analytics_limit burst=20 nodelay;
    proxy_pass https://app.rybbit.io/api/track;
    # ... proxy headers
}
```

This limits to 10 requests per second per IP, with bursts up to 20.

### Request Size Limits [#request-size-limits]

Set appropriate limits for different endpoints:

```nginx
# Default for most endpoints
client_max_body_size 1M;

# Larger limit for session replay
location ~ ^/analytics/session-replay/record/ {
    client_max_body_size 10M;
    # ... proxy config
}
```

### Security Headers [#security-headers]

Add security headers to your responses:

```nginx
add_header X-Content-Type-Options nosniff;
add_header X-Frame-Options DENY;
add_header Referrer-Policy strict-origin-when-cross-origin;
```

## Troubleshooting [#troubleshooting]

### 502 Bad Gateway [#502-bad-gateway]

**Problem**: Nginx returns 502 error when accessing analytics endpoints.

**Solution**:

1. Check Rybbit backend is accessible:
   ```bash
   curl -I https://app.rybbit.io/api/script.js
   ```
2. Verify `proxy_ssl_server_name on` is set
3. Check Nginx error logs:
   ```bash
   sudo tail -f /var/log/nginx/error.log
   ```

### Cache not working [#cache-not-working]

**Problem**: `X-Cache-Status` always shows `MISS`.

**Solution**:

1. Verify cache directory exists and is writable
2. Check `proxy_cache_path` is defined in http block
3. Ensure `proxy_cache` directive uses correct zone name
4. Check cache key is consistent:
   ```nginx
   proxy_cache_key "$scheme$request_method$host$request_uri";
   ```

### Incorrect geolocation in Rybbit [#incorrect-geolocation-in-rybbit]

**Problem**: All visitors show same location (your server's location).

**Solution**:
Ensure you're forwarding client IP headers:

```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
```

### SSL errors in Nginx logs [#ssl-errors-in-nginx-logs]

**Problem**: Logs show SSL verification errors when connecting to Rybbit.

**Solution**:
Add `proxy_ssl_server_name on` to enable SNI:

```nginx
location /analytics/ {
    proxy_pass https://app.rybbit.io/api/;
    proxy_ssl_server_name on;  # Enable SNI
    # ... other config
}
```

## Advanced Configuration [#advanced-configuration]

### Subdomain Proxy [#subdomain-proxy]

Use a dedicated subdomain for analytics:

```nginx
# /etc/nginx/sites-available/analytics.yourdomain.com
server {
    listen 443 ssl http2;
    server_name analytics.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/analytics.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.yourdomain.com/privkey.pem;

    # Proxy all requests to Rybbit
    location / {
        proxy_pass https://app.rybbit.io/api/;
        proxy_set_header Host app.rybbit.io;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_ssl_server_name on;
    }
}
```

Then use:

```html
<script src="https://analytics.yourdomain.com/script.js" data-site-id="123"></script>
```

### Multiple Rybbit Instances [#multiple-rybbit-instances]

If you need to proxy multiple Rybbit instances:

```nginx
location /analytics-prod/ {
    proxy_pass https://prod.rybbit.io/api/;
    # ... proxy config
}

location /analytics-staging/ {
    proxy_pass https://staging.rybbit.io/api/;
    # ... proxy config
}
```

## Related Resources [#related-resources]

* [Nginx Custom Configuration Guide](/docs/self-hosting-guides/custom-nginx) - Self-hosting Rybbit with Nginx
* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Framework-agnostic concepts
* [Nginx Proxy Module](http://nginx.org/en/docs/http/ngx_http_proxy_module.html) - Official Nginx documentation


# Troubleshooting Proxy Setup (/docs/proxy-guide/troubleshooting)





This guide covers common issues you might encounter when setting up a Rybbit proxy and how to resolve them.

## Script Loading Issues [#script-loading-issues]

### Script Fails to Load (404 Error) [#script-fails-to-load-404-error]

**Symptoms:**

* Network tab shows 404 for `/analytics/script.js`
* Console errors about failed script loading
* No tracking data in dashboard

**Solutions:**

<Steps>
  ### Verify Proxy Configuration [#verify-proxy-configuration]

  Check your proxy rules are correctly configured:

  * **Next.js**: Ensure rewrites are in `next.config.js` and server is restarted
  * **Nginx**: Verify location blocks are active and Nginx is reloaded
  * **Caddy**: Check Caddyfile syntax with `caddy validate`
  * **Workers**: Verify route is configured in Cloudflare dashboard

  ### Check Path Mapping [#check-path-mapping]

  Ensure paths are correctly mapped:

  ```
  Your domain          →  Rybbit backend
  -----------------        ---------------
  /analytics/script.js →  /api/script.js
  ```

  Common mistakes:

  * Wrong source path (`/tracking` instead of `/analytics`)
  * Incorrect destination (missing `/api` prefix)
  * Typos in configuration

  ### Test Direct Backend Access [#test-direct-backend-access]

  Verify Rybbit backend is accessible:

  ```bash
  curl -I https://app.rybbit.io/api/script.js
  ```

  Should return `HTTP/2 200` with `content-type: application/javascript`.
</Steps>

***

### Script Loads but Returns HTML [#script-loads-but-returns-html]

**Symptoms:**

* Script loads with 200 status
* Content-Type is `text/html` instead of `application/javascript`
* Console errors about unexpected token `<`

**Cause:** Proxy is serving your application's 404 page instead of proxying.

**Solutions:**

1. **Ensure proxy runs before app routing**:
   * Next.js: Rewrites run automatically before pages
   * Express: Define proxy routes BEFORE catch-all routes
   * Laravel: Place proxy routes at the top of `web.php`

2. **Check route specificity**:

```javascript
// ❌ Wrong order - catch-all comes first
app.get('*', (req, res) => res.sendFile('index.html'));
app.use('/analytics', proxyMiddleware);

// ✅ Correct order - proxy comes first
app.use('/analytics', proxyMiddleware);
app.get('*', (req, res) => res.sendFile('index.html'));
```

***

## Tracking Issues [#tracking-issues]

### Script Loads but No Events Tracked [#script-loads-but-no-events-tracked]

**Symptoms:**

* Script loads successfully
* No errors in console
* No tracking data appears in Rybbit dashboard
* POST requests to `/analytics/track` fail or return errors

**Solutions:**

<Steps>
  ### Verify All Endpoints Are Proxied [#verify-all-endpoints-are-proxied]

  Ensure tracking endpoints are configured:

  * `/analytics/track` (required)
  * `/analytics/identify` (for user identification)
  * `/analytics/session-replay/record/:siteId` (for session replay)
  * `/analytics/site/tracking-config/:siteId` (for configuration)

  **Check Network tab**: Look for failed POST requests to `/analytics/track`.

  ### Check CORS Headers [#check-cors-headers]

  Tracking endpoints need proper CORS headers. Rybbit sets these automatically, but ensure your proxy preserves them:

  ```nginx
  # Nginx - preserve CORS headers
  proxy_pass_header Access-Control-Allow-Origin;
  proxy_pass_header Access-Control-Allow-Methods;
  ```

  ```javascript
  // Express - don't override CORS
  // ❌ Wrong - blocks CORS
  app.use('/analytics', cors({ origin: 'https://yourdomain.com' }));

  // ✅ Correct - allow all origins (or use Rybbit's headers)
  app.use('/analytics', cors({ origin: true }));
  ```

  ### Verify Content-Type for POST Requests [#verify-content-type-for-post-requests]

  Tracking POSTs send JSON data. Ensure Content-Type is preserved:

  ```nginx
  # Nginx
  proxy_set_header Content-Type $content_type;
  ```

  ```javascript
  // Express
  onProxyReq: (proxyReq, req) => {
    if (req.headers['content-type']) {
      proxyReq.setHeader('Content-Type', req.headers['content-type']);
    }
  }
  ```

  ### Check Request Method Preservation [#check-request-method-preservation]

  Ensure POST requests remain POST:

  ```nginx
  # Nginx - correct
  proxy_method $request_method;

  # Or let it default (preserves method)
  proxy_pass https://app.rybbit.io;
  ```
</Steps>

***

### Events Tracked but Dashboard Shows Wrong Data [#events-tracked-but-dashboard-shows-wrong-data]

**Symptoms:**

* Events appear in dashboard
* But geolocation is wrong (all same location)
* Or user agents are incorrect

**Cause:** Client IP or headers not forwarded properly.

**Solutions:**

<Callout type="warn">
  **Critical**: The `X-Forwarded-For` header must contain the original client IP for accurate geolocation and user identification, and the **First-Party Proxy** toggle must be enabled in your site settings. Don't rely on `X-Real-IP` — on Rybbit Cloud it never reaches the backend (our edge network consumes it), and AWS CloudFront cannot send it at all.
</Callout>

**Nginx:**

```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header User-Agent $http_user_agent;
```

**Caddy:**

```txt
reverse_proxy https://app.rybbit.io {
    header_up X-Real-IP {remote_host}
    header_up X-Forwarded-For {remote_host}
}
```

**Express:**

```javascript
onProxyReq: (proxyReq, req) => {
  const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  proxyReq.setHeader('X-Real-IP', clientIp);
  proxyReq.setHeader('X-Forwarded-For', clientIp);
  proxyReq.setHeader('User-Agent', req.headers['user-agent']);
}
```

**Cloudflare Workers:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';
proxyHeaders.set('X-Forwarded-For', clientIp);
```

***

### Proxied Requests Are Detected as Bots [#proxied-requests-are-detected-as-bots]

**Symptoms:**

* `/analytics/track` returns `200 OK`
* Events do not appear in the normal analytics dashboard (only under bot traffic)
* Tracking works fine when the script talks to Rybbit directly, without the proxy

There are two independent causes, and server-side proxies often hit **both**. Work through them in order.

#### Cause 1: Your proxy strips the browser's headers [#cause-1-your-proxy-strips-the-browsers-headers]

Rybbit's bot detection scores requests on headers that every real browser sends: `Accept`, `Accept-Language`, `Accept-Encoding` (with `gzip`), and the `Sec-Fetch-*` headers that all Chromium browsers attach. A proxy that forwards only `User-Agent` and the visitor IP produces requests indistinguishable from a script — they are accepted with `200 OK` but classified as bots.

**Fix:** forward **all** incoming request headers, minus `Host` and hop-by-hop headers (`Connection`, `Content-Length`). Hand-picking headers is the most common mistake in PHP/WordPress-style proxies.

```php
// PHP example — forward everything except Host/hop-by-hop
$headers = [];
foreach (getallheaders() as $name => $value) {
    if (!in_array(strtolower($name), ['host', 'connection', 'content-length'])) {
        $headers[] = "$name: $value";
    }
}
$headers[] = 'X-Forwarded-For: ' . $_SERVER['REMOTE_ADDR'];
```

#### Cause 2: Rybbit sees your proxy's IP instead of the visitor's [#cause-2-rybbit-sees-your-proxys-ip-instead-of-the-visitors]

First-party proxies typically run on hosting/datacenter infrastructure, so if the visitor IP is not forwarded (or not trusted), traffic carries a datacenter ASN and reinforces bot classification — and geolocation points at your proxy's region.

**Fix:**

1. Set `X-Forwarded-For` to the original visitor IP before forwarding to Rybbit.
2. Enable the **First-Party Proxy** toggle in **Site Settings → Privacy & Security** so Rybbit trusts the forwarded IP unconditionally.

<Callout type="warn">
  Use `X-Forwarded-For`, not `X-Real-IP`. On Rybbit Cloud, `X-Real-IP` never reaches the backend (our edge network consumes it), and AWS CloudFront cannot send it at all.
</Callout>

**Cloudflare Workers:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

const proxyHeaders = new Headers(request.headers); // preserves all browser headers
proxyHeaders.set('X-Forwarded-For', clientIp);
```

**AWS CloudFront:**

* Set `X-Forwarded-For` to the viewer IP from a CloudFront Function/Lambda\@Edge
* Configure the origin request policy to forward all viewer headers

```javascript
// CloudFront Function (viewer-request)
function handler(event) {
  event.request.headers["x-forwarded-for"] = { value: event.viewer.ip };
  return event.request;
}
```

***

## Session Replay Issues [#session-replay-issues]

### Session Replay Not Working [#session-replay-not-working]

**Symptoms:**

* Basic tracking works fine
* Session replays don't appear in dashboard
* Console shows errors loading `/analytics/replay.js`

**Solutions:**

1. **Add replay script endpoint**:

```javascript
// Next.js
{
  source: '/analytics/replay.js',
  destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/replay.js`,
}
```

2. **Add replay recording endpoint**:

```javascript
{
  source: '/analytics/session-replay/record/:siteId',
  destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/session-replay/record/:siteId`,
}
```

3. **Increase request size limits**:

Session replay can send large payloads (up to 10MB). Ensure your proxy allows this:

```nginx
# Nginx
location ~ ^/analytics/session-replay/record/ {
    client_max_body_size 10M;
    proxy_pass https://app.rybbit.io;
}
```

```javascript
// Express
app.use('/analytics/session-replay', express.json({ limit: '10mb' }));
```

```javascript
// Next.js - add to next.config.js
module.exports = {
  api: {
    bodyParser: {
      sizeLimit: '10mb',
    },
  },
};
```

***

## Configuration and Caching Issues [#configuration-and-caching-issues]

### Stale Configuration (Settings Changes Not Applied) [#stale-configuration-settings-changes-not-applied]

**Symptoms:**

* Changed settings in Rybbit dashboard
* But tracking script still uses old settings
* Takes a long time for changes to appear

**Cause:** Configuration endpoint is cached too aggressively.

**Solutions:**

1. **Check cache duration** for config endpoint:

```nginx
# Nginx - cache for 5 minutes max
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_cache_valid 200 5m;  # Not longer!
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
}
```

2. **Clear cache manually**:

```bash
# Nginx
sudo nginx -s reload

# Or clear cache directory
sudo rm -rf /var/cache/nginx/rybbit/*
```

```javascript
// Node.js/Express with node-cache
cache.del(`rybbit_config_${siteId}`);

// Or flush all
cache.flushAll();
```

3. **Don't cache config endpoint at all** (if issues persist):

```nginx
# Nginx - no caching
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_cache off;
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
}
```

***

### Script Updates Not Appearing [#script-updates-not-appearing]

**Symptoms:**

* Rybbit released an update
* Your site still loads old script version
* Missing new features or bug fixes

**Cause:** Script cached too long.

**Solutions:**

1. **Recommended cache duration**: 1 hour maximum

```nginx
# Nginx
proxy_cache_valid 200 1h;  # Not longer!
```

2. **Clear script cache**:

```bash
# Nginx - purge cache
sudo rm -rf /var/cache/nginx/rybbit/
sudo nginx -s reload
```

```bash
# Vercel - clear via dashboard
# Deployments → Your deployment → Clear cache
```

```javascript
// Cloudflare Workers - purge via dashboard
// Caching → Configuration → Purge Everything
```

3. **Add cache busting** (advanced):

```javascript
// Next.js - revalidate on each deployment
{
  source: '/analytics/script.js',
  destination: `${rybbitHost}/api/script.js`,
  headers: [
    {
      key: 'Cache-Control',
      value: 'public, max-age=3600, must-revalidate',
    },
  ],
}
```

***

## Performance Issues [#performance-issues]

### High Bandwidth Usage [#high-bandwidth-usage]

**Symptoms:**

* Bandwidth costs increasing significantly
* Server struggling with traffic
* Slow response times

**Solutions:**

<Steps>
  ### Implement Caching [#implement-caching]

  Cache static scripts to reduce backend requests:

  ```nginx
  # Nginx with caching
  proxy_cache_path /var/cache/nginx/rybbit levels=1:2 keys_zone=rybbit:10m;

  location = /analytics/script.js {
      proxy_cache rybbit;
      proxy_cache_valid 200 1h;
      proxy_cache_key "$scheme$request_method$host$request_uri";
      add_header X-Cache-Status $upstream_cache_status;
      proxy_pass https://app.rybbit.io/api/script.js;
  }
  ```

  ### Use CDN [#use-cdn]

  Put a CDN in front of your proxy:

  * Cloudflare (recommended)
  * AWS CloudFront
  * Fastly

  ### Monitor and Limit [#monitor-and-limit]

  Add monitoring and rate limiting:

  ```javascript
  // Express with rate limiting
  const rateLimit = require('express-rate-limit');

  app.use('/analytics/track', rateLimit({
    windowMs: 60 * 1000,
    max: 100, // 100 requests per minute per IP
  }));
  ```
</Steps>

***

### Slow Response Times [#slow-response-times]

**Symptoms:**

* Tracking requests take multiple seconds
* Script loading is slow
* Poor user experience

**Solutions:**

1. **Enable compression**:

```nginx
# Nginx
gzip on;
gzip_types application/javascript;
```

2. **Use connection keepalive**:

```nginx
# Nginx
proxy_http_version 1.1;
proxy_set_header Connection "";

upstream rybbit {
    server app.rybbit.io:443;
    keepalive 32;
}
```

3. **Check backend connectivity**:

```bash
# Test latency to Rybbit
curl -w "@curl-format.txt" -o /dev/null -s https://app.rybbit.io/api/script.js

# Create curl-format.txt:
# time_namelookup:  %{time_namelookup}s
# time_connect:     %{time_connect}s
# time_starttransfer: %{time_starttransfer}s
# time_total:       %{time_total}s
```

If backend is slow, consider:

* Self-hosting Rybbit closer to your users
* Using a CDN proxy
* Caching more aggressively

***

## Platform-Specific Issues [#platform-specific-issues]

### Next.js: Rewrites Not Working [#nextjs-rewrites-not-working]

**Problem:** Added rewrites to `next.config.js` but they don't work.

**Solutions:**

1. **Restart dev server**:

```bash
# Stop server (Ctrl+C)
npm run dev
```

2. **Check async rewrites** function:

```javascript
// ❌ Wrong - not async
rewrites() {
    return [...];
}

// ✅ Correct - async
async rewrites() {
    return [...];
}
```

3. **Verify environment variable** is loaded:

```javascript
async rewrites() {
    console.log('RYBBIT_HOST:', process.env.NEXT_PUBLIC_RYBBIT_HOST);
    // Should log the URL
    return [...];
}
```

***

### Nginx: 502 Bad Gateway [#nginx-502-bad-gateway]

**Problem:** Nginx returns 502 error for analytics endpoints.

**Solutions:**

1. **Enable SNI** for SSL:

```nginx
proxy_ssl_server_name on;
```

2. **Check DNS resolution**:

```bash
nslookup app.rybbit.io
```

3. **Check logs**:

```bash
sudo tail -f /var/log/nginx/error.log
```

4. **Test backend directly**:

```bash
curl -v https://app.rybbit.io/api/script.js
```

***

### Vercel: 404 After Deployment [#vercel-404-after-deployment]

**Problem:** Works locally but 404 in production.

**Solutions:**

1. **Ensure `vercel.json` is committed**:

```bash
git add vercel.json
git commit -m "Add Rybbit proxy config"
git push
```

2. **Check build logs** in Vercel dashboard for errors

3. **Verify environment variables** are set in Vercel project settings

***

## Debugging Checklist [#debugging-checklist]

When troubleshooting, work through this checklist:

* [ ] Script loads successfully (200 status, correct Content-Type)
* [ ] Tracking endpoint is proxied (`/analytics/track`)
* [ ] POST requests preserve method and body
* [ ] Client IP is forwarded in `X-Forwarded-For` (not just `X-Real-IP` — that header doesn't survive Rybbit Cloud's edge)
* [ ] **First-Party Proxy** toggle is enabled in Site Settings → Privacy & Security
* [ ] Full browser header set is forwarded (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — not just `User-Agent`
* [ ] User-Agent header is preserved
* [ ] CORS headers are preserved (check response headers)
* [ ] Request size limits allow tracking data (1MB minimum)
* [ ] Session replay endpoints are proxied (if using replay)
* [ ] Cache duration is appropriate (1 hour for scripts, 5 min for config)
* [ ] No CSRF protection blocking POST requests
* [ ] Environment variables are set correctly
* [ ] Configuration changes have been deployed

## Getting Help [#getting-help]

If you've tried everything and still have issues:

1. **Check browser console** for JavaScript errors
2. **Check Network tab** for failed requests (note status codes)
3. **Check server logs** for proxy errors
4. **Test with curl** to isolate browser vs server issues
5. **Verify directly** against `https://app.rybbit.io/api/script.js`

**Gather this information before asking for help:**

* Framework/platform you're using
* Proxy configuration code
* Network tab screenshot showing the issue
* Any error messages from logs or console
* Whether it worked before (what changed?)

## Related Resources [#related-resources]

* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [Tracking Script Documentation](/docs/script) - Script configuration
* Framework-specific guides for detailed setup


# Vercel Proxy Setup (/docs/proxy-guide/vercel)





Vercel makes it easy to proxy Rybbit tracking through their Edge Network. If you're using Next.js, follow the [Next.js proxy guide](/docs/proxy-guide/next-js) instead, which is optimized for Next.js applications.

This guide is for static sites or other frameworks deployed on Vercel.

<Callout type="info">
  Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**. Rewrites on this platform automatically forward the browser's headers and set `X-Forwarded-For` to the visitor IP — the toggle tells Rybbit to trust that forwarded IP directly.
</Callout>

## Overview [#overview]

Vercel supports rewrites in `vercel.json`, allowing you to proxy requests through their global Edge Network. This provides excellent performance with automatic caching at edge locations worldwide.

**What you'll achieve:**

* Proxy Rybbit through Vercel's Edge Network
* Automatic global caching and CDN distribution
* Simple JSON configuration
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Site deployed on Vercel
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Create or Update vercel.json [#create-or-update-verceljson]

  Add rewrites to your `vercel.json` file in the project root:

  ```json
  {
    "rewrites": [
      {
        "source": "/analytics/script.js",
        "destination": "https://app.rybbit.io/api/script.js"
      },
      {
        "source": "/analytics/replay.js",
        "destination": "https://app.rybbit.io/api/replay.js"
      },
      {
        "source": "/analytics/metrics.js",
        "destination": "https://app.rybbit.io/api/metrics.js"
      },
      {
        "source": "/analytics/track",
        "destination": "https://app.rybbit.io/api/track"
      },
      {
        "source": "/analytics/identify",
        "destination": "https://app.rybbit.io/api/identify"
      },
      {
        "source": "/analytics/session-replay/record/:siteId",
        "destination": "https://app.rybbit.io/api/session-replay/record/:siteId"
      },
      {
        "source": "/analytics/site/tracking-config/:siteId",
        "destination": "https://app.rybbit.io/api/site/tracking-config/:siteId"
      }
    ]
  }
  ```

  <Callout type="info">
    Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to use the proxied path:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Deploy to Vercel [#deploy-to-vercel]

  Commit your changes and deploy:

  ```bash
  git add vercel.json
  git commit -m "Add Rybbit proxy configuration"
  git push
  ```

  Vercel will automatically detect the changes and deploy with the new rewrites.

  ### Verify the Setup [#verify-the-setup]

  1. **Visit your deployed site** with Developer Tools open
  2. **Check Network tab**:
     * Script should load from `/analytics/script.js`
     * Tracking requests should go to `/analytics/track`
     * All requests should show your Vercel domain
  3. **Verify in Rybbit dashboard**: Data should appear after 1-2 minutes
</Steps>

## How It Works [#how-it-works]

Vercel's Edge Network handles rewrites at the edge, close to your users:

1. Request hits Vercel's edge location nearest to the user
2. Edge server rewrites and proxies to Rybbit
3. Response is cached at the edge (for cacheable requests)
4. Subsequent requests serve from edge cache

This provides excellent performance with minimal configuration.

## Performance Benefits [#performance-benefits]

### Edge Network Caching [#edge-network-caching]

Vercel automatically caches responses at edge locations:

* **Scripts**: Cached globally, served from nearest edge
* **Configuration**: Cached with appropriate TTL
* **Tracking requests**: Not cached (unique per request)

### Global Distribution [#global-distribution]

Your analytics proxy benefits from Vercel's global CDN:

* 70+ edge locations worldwide
* Sub-100ms latency for most users
* Automatic failover and redundancy

## Bandwidth Considerations [#bandwidth-considerations]

<Callout type="warn">
  Vercel rewrites count toward your bandwidth quota. For a site with 100,000 monthly sessions:

  * Without session replay: \~5-10 GB/month
  * With session replay: \~30-80 GB/month

  Check your Vercel plan limits. Pro plan includes 1 TB bandwidth/month.
</Callout>

## Troubleshooting [#troubleshooting]

### Rewrites not working [#rewrites-not-working]

**Problem**: Requests still go to `app.rybbit.io` directly.

**Solution**:

1. Ensure `vercel.json` is in your project root
2. Redeploy after adding `vercel.json`
3. Clear browser cache and test in incognito mode

### 404 on tracking endpoints [#404-on-tracking-endpoints]

**Problem**: Script loads but tracking returns 404.

**Solution**:
Verify all endpoints are in `vercel.json` rewrites, including:

* `/analytics/track`
* `/analytics/identify`
* `/analytics/session-replay/record/:siteId`

### Session replay not working [#session-replay-not-working]

**Problem**: Basic tracking works but replay doesn't record.

**Solution**:
Add replay endpoints to rewrites:

```json
{
  "source": "/analytics/replay.js",
  "destination": "https://app.rybbit.io/api/replay.js"
},
{
  "source": "/analytics/session-replay/record/:siteId",
  "destination": "https://app.rybbit.io/api/session-replay/record/:siteId"
}
```

## Environment-Specific Configuration [#environment-specific-configuration]

### Using Environment Variables [#using-environment-variables]

While Vercel's `vercel.json` doesn't support environment variables directly, you can use different config files:

```json
// vercel.json (production)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}
```

```json
// vercel.staging.json (staging)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://staging.rybbit.io/api/script.js"
    }
  ]
}
```

Then specify config in build settings or use Vercel CLI:

```bash
vercel --prod --local-config vercel.json
```

## Advanced Configuration [#advanced-configuration]

### Headers [#headers]

Add custom headers to responses:

```json
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ],
  "headers": [
    {
      "source": "/analytics/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=3600"
        }
      ]
    }
  ]
}
```

### Redirects vs Rewrites [#redirects-vs-rewrites]

Don't use redirects for proxying (they're visible to the user):

```json
// ❌ Wrong - uses redirects (user sees app.rybbit.io)
{
  "redirects": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}

// ✅ Correct - uses rewrites (transparent proxy)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}
```

## Related Resources [#related-resources]

* [Next.js Proxy Guide](/docs/proxy-guide/next-js) - If using Next.js
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Vercel Rewrites Documentation](https://vercel.com/docs/projects/project-configuration#rewrites) - Official Vercel docs


# JavaScript (Node.js) (/docs/sdks/node)





## Installation [#installation]

```bash filename="npm"
npm install @rybbit/node
```

```bash filename="yarn"
yarn add @rybbit/node
```

## Initialization [#initialization]

### Syntax [#syntax]

```typescript
import { Rybbit } from "@rybbit/node";

const rybbit = new Rybbit(config: RybbitConfig);
```

### Example [#example]

```javascript
import { Rybbit } from "@rybbit/node";

const rybbit = new Rybbit({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  apiKey: "your-secret-api-key",
});
```

<Callout type="warning">
  The `Rybbit` constructor will throw an error if required configuration options (`analyticsHost`, `siteId`, `apiKey`) are missing or invalid.
</Callout>

### Configuration Options [#configuration-options]

| Option          | Type               | Default | Description                                                                                      |
| :-------------- | :----------------- | :------ | :----------------------------------------------------------------------------------------------- |
| `analyticsHost` | `string`           | -       | **Required.** URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |
| `siteId`        | `string \| number` | -       | **Required.** The Site ID for your website obtained from your Rybbit instance.                   |
| `apiKey`        | `string`           | -       | **Required.** Your secret API key for the site                                                   |
| `debug`         | `boolean`          | `false` | Enable detailed logging to the console.                                                          |

## Tracking Pageviews [#tracking-pageviews]

While pageviews are traditionally a browser concept, the Node.js SDK provides a `pageview` method to track events that are analogous to a user viewing a page or a significant resource. This can be useful for tracking views of server-rendered pages before client-side JavaScript takes over, or for tracking views of API resources.

### Syntax [#syntax-1]

```typescript
await rybbit.pageview(payload?: Payload);
```

### Parameters [#parameters]

* **`payload`** (`object`, Optional): An object containing details about the pageview. All properties are optional.
  * `hostname` (`string`): The hostname associated with this pageview.
  * `pathname` (`string`): The path of the page/resource being viewed.
  * `querystring` (`string`): Any query parameters associated with the path.
  * `screenWidth` (`number`): Screen width in pixels.
  * `screenHeight` (`number`): Screen height in pixels.
  * `language` (`string`): Language code.
  * `page_title` (`string`): The title of the page or resource.
  * `referrer` (`string`): The referrer URL.
  * `user_id` (`string`): A unique identifier for the user.
  * `user_agent` (`string`): The user agent string of the client.
  * `ip_address` (`string`): The IP address of the client.

<Callout type="info">
  The fields `screenWidth`, `screenHeight`, `language`, `page_title`, and `referrer` are typically browser-derived. When using the Node.js SDK, you would only provide these if they are relevant and available in your server-side context. For many server-side pageview events, `hostname` and `pathname` might be the most relevant.
</Callout>

### Example [#example-1]

```javascript
// Track a server-rendered page view
async function handleProductPageRequest(req, res) {
  // ... server logic to render product page ...

  await rybbit.pageview({
    hostname: req.hostname,
    pathname: `/products/${req.params.productId}`,
    page_title: `Product - ${product.name}`,
    ip_address: req.ip
  });

  // ... send response ...
}

// Track an API resource view
async function serveApiResource(req) {
  await rybbit.pageview({
    hostname: "api.myservice.com",
    pathname: `/v1/items/${req.params.itemId}`,
    user_id: req.user.id,
    ip_address: req.ip
  });
  // ... return API data ...
}
```

## Tracking Custom Events [#tracking-custom-events]

Use custom events to track specific actions or milestones occurring in your backend system. Examples include user account creation, background job completion, API endpoint usage, or any significant server-side process.

### Syntax [#syntax-2]

```typescript
await rybbit.event(eventName: string, payload?: Payload, properties?: TrackProperties);
```

### Parameters [#parameters-1]

* **`eventName`** (`string`, Required): The name of the event you want to track.
* **`payload`** (`object`, Optional): An object containing contextual details for the event. All properties are optional.
  * `hostname` (`string`): The hostname associated with this event.
  * `pathname` (`string`): The path or resource context for this event.
  * `querystring` (`string`): Any query parameters relevant to the event's context.
  * `screenWidth` (`number`): Screen width in pixels.
  * `screenHeight` (`number`): Screen height in pixels.
  * `language` (`string`): Language code.
  * `page_title` (`string`): The title of the page or resource context.
  * `referrer` (`string`): The referrer URL.
  * `user_id` (`string`): A unique identifier for the user.
  * `user_agent` (`string`): The user agent string of the client.
  * `ip_address` (`string`): The IP address of the client.
* **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values can be a `string`, `number`, `boolean`, or an array of these types.

<Callout type="info">
  The `payload` fields (`hostname`, `pathname`, etc.) provide general context for the event, similar to a pageview. The `properties` object is for data specific to the custom `eventName` itself (e.g., for an `"order_processed"` event, properties might include `orderId: 12345` and `totalAmount: 99.99`).
</Callout>

### Example [#example-2]

```javascript
// Track a new user registration
async function registerUser(userData, req) {
  // ... process user registration ...

  await rybbit.event("user_registered",
    {
      hostname: "auth.myservice.com",
      pathname: "/register",
      ip_address: req.ip
    },
    {
      userId: newUserId,
      registrationMethod: "email"
    }
  );
}

// Track a background job completion
async function processDailyReport(reportId) {
  // ... generate report ...

  await rybbit.event("report_generated",
    {},
    {
      reportId: reportId,
      status: "success",
      processingTimeMs: 12345
    }
  );
}

// Track an API endpoint usage with specific data
async function handleApiRequest(req) {
    // ... handle request ...
    await rybbit.event(
        "api_v1_item_lookup",
        {
          hostname: req.hostname,
          pathname: req.path,
          user_id: req.user.id,
          ip_address: req.ip
        },
        {
          itemId: req.params.itemId,
          clientVersion: req.headers["x-client-version"]
        }
    );
    // ... return response ...
}
```


# React Native (/docs/sdks/react-native)





The `@rybbit/react-native` SDK lets you track screens, events, errors, and users in React Native apps. Mobile sites get an App Analytics dashboard mode with mobile-specific labels (e.g. screen views instead of pageviews).

## Creating a Mobile App Site [#creating-a-mobile-app-site]

Before installing the SDK, create a site for your app in the Rybbit dashboard:

1. Click **Add Site** and select the **React Native app** option instead of Website.
2. Enter an app identifier (e.g. `com.example.app`). Letters, numbers, dots, hyphens, and underscores are allowed.
3. Copy the Site ID — you'll pass it to `init()`.

## Installation [#installation]

```bash
npm install @rybbit/react-native @react-native-async-storage/async-storage
```

<Callout type="info">
  `@react-native-async-storage/async-storage` is recommended but not strictly required. The SDK accepts any storage adapter with `getItem`/`setItem`/`removeItem`. Without one, it falls back to in-memory storage and the anonymous visitor ID will not persist across app launches, so every launch counts as a new visitor.
</Callout>

## Initialization [#initialization]

<Callout type="warning">
  `rybbit.init()` **must** be called once before any other tracking methods. Calling other methods first throws an error.
</Callout>

### Syntax [#syntax]

```typescript
async rybbit.init(config: RybbitConfig): Promise<void>;
```

### Example [#example]

```tsx
import AsyncStorage from "@react-native-async-storage/async-storage";
import rybbit from "@rybbit/react-native";

await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  appIdentifier: "com.example.app",
  appVersion: "1.4.2",
  storage: AsyncStorage,
  initialScreenName: "Home",
});
```

### Configuration Options [#configuration-options]

#### Required Options [#required-options]

| Option          | Type               | Description                                                                    |
| :-------------- | :----------------- | :----------------------------------------------------------------------------- |
| `analyticsHost` | `string`           | URL of your Rybbit instance's API (e.g., `https://rybbit.yourdomain.com/api`). |
| `siteId`        | `string \| number` | The Site ID for your app obtained from your Rybbit instance.                   |

#### Optional Options [#optional-options]

| Option                  | Type            | Default     | Description                                                                                                                          |
| :---------------------- | :-------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `appIdentifier`         | `string`        | `""`        | Identifier for your app (e.g., `com.example.app`). Used as the hostname in tracked data. Falls back to `bundleId`, then the site ID. |
| `bundleId`              | `string`        | `""`        | Alias for `appIdentifier`; used when `appIdentifier` is not set.                                                                     |
| `appVersion`            | `string`        | `""`        | Your app's version. Appended to the synthetic user agent sent with each event.                                                       |
| `tag`                   | `string`        | `""`        | A tag added to every event, useful for segmenting data (e.g., by environment or build channel).                                      |
| `storage`               | `RybbitStorage` | in-memory   | Storage adapter used to persist the anonymous visitor ID and identified user ID. Pass `AsyncStorage` or any compatible object.       |
| `storageKeyPrefix`      | `string`        | `"@rybbit"` | Prefix for storage keys. Keys are namespaced per site: `{prefix}:{siteId}:anonymous-id`.                                             |
| `debug`                 | `boolean`       | `false`     | Log SDK warnings (failed requests, config fetch failures) to the console.                                                            |
| `autoTrackAppLifecycle` | `boolean`       | `true`      | Automatically track `app_open` and `app_background` events on `AppState` changes. See [App Lifecycle Events](#app-lifecycle-events). |
| `initialScreenName`     | `string`        | `""`        | If set, a screen view for this name is tracked during `init()` (unless Track Initial Pageview is disabled in your dashboard).        |
| `configTimeoutMs`       | `number`        | `3000`      | Timeout in milliseconds for fetching remote tracking config during `init()`. On timeout or failure, the SDK proceeds with defaults.  |
| `maxQueueSize`          | `number`        | `100`       | Maximum number of failed events kept in the in-memory retry queue. See [Offline Handling](#offline-handling-and-retries).            |
| `fetch`                 | `typeof fetch`  | global      | Custom `fetch` implementation. Defaults to the global `fetch`.                                                                       |

#### Remote Configuration [#remote-configuration]

During `init()`, the SDK fetches your site's tracking settings from the dashboard. Two of them affect the React Native SDK:

| Dashboard Setting      | Effect                                                                     |
| :--------------------- | :------------------------------------------------------------------------- |
| Track Initial Pageview | When disabled, the `initialScreenName` screen view is not tracked on init. |
| Capture Errors         | When disabled, calls to `rybbit.error()` are silently ignored.             |

Web-only settings (session replay, Web Vitals, outbound links, autocapture) do not apply to mobile apps.

## Tracking Screens [#tracking-screens]

Screens are the mobile equivalent of pageviews. Each screen view is tracked with the screen name as both the path and title.

### Syntax [#syntax-1]

```typescript
rybbit.screen(name: string, properties?: TrackProperties, context?: TrackContext): Promise<void>;
```

### Parameters [#parameters]

* **`name`** (`string`, Required): The screen name (e.g., `"Home"`, `"Checkout"`). Used as the pathname (`/Home`) and page title.
* **`properties`** (`object`, Optional): Additional key-value pairs attached to the screen view.
* **`context`** (`object`, Optional): Overrides for the tracked payload. See [Track Context](#track-context).

### Example [#example-1]

```tsx
await rybbit.screen("Checkout");

// With properties and an explicit path
await rybbit.screen("Product", { productId: "sku-123" }, { pathname: "/products/sku-123" });
```

You can also track a raw path directly, mirroring the web SDK:

```typescript
rybbit.pageview(path?: string, context?: TrackContext): Promise<void>;
```

## React Navigation [#react-navigation]

The SDK ships a navigation tracker that hooks into React Navigation's `NavigationContainer` and automatically tracks a screen view whenever the active route changes. Consecutive events for the same route name are deduplicated.

```tsx
import { NavigationContainer, useNavigationContainerRef } from "@react-navigation/native";
import rybbit from "@rybbit/react-native";

const navigationTracker = rybbit.createNavigationTracker();

function App() {
  const navigationRef = useNavigationContainerRef();

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => navigationTracker.onReady(navigationRef)}
      onStateChange={() => navigationTracker.onStateChange(navigationRef)}
    >
      {/* screens */}
    </NavigationContainer>
  );
}
```

### Options [#options]

```typescript
rybbit.createNavigationTracker(options?: NavigationTrackerOptions): NavigationTracker;
```

| Option               | Type                | Default                      | Description                                                                |
| :------------------- | :------------------ | :--------------------------- | :------------------------------------------------------------------------- |
| `includeRouteParams` | `boolean`           | `false`                      | Include the route's params as a `routeParams` property on the screen view. |
| `getRouteName`       | `(route) => string` | `route.name`                 | Customize how the screen name is derived from the current route.           |
| `getPath`            | `(route) => string` | `route.path` or `route.name` | Customize the tracked pathname for the current route.                      |

The returned tracker exposes `onReady`, `onStateChange`, and `trackCurrentRoute` — all take the navigation ref and track the current route if it changed. It works with any navigation library whose ref exposes a `getCurrentRoute()` method.

<Callout type="warning">
  Route params can contain sensitive data (IDs, tokens, emails). Only enable `includeRouteParams` if your route params are safe to store in analytics.
</Callout>

## Tracking Custom Events [#tracking-custom-events]

### Syntax [#syntax-2]

```typescript
rybbit.event(name: string, properties?: TrackProperties, context?: TrackContext): Promise<void>;
```

### Parameters [#parameters-1]

* **`name`** (`string`, Required): The name of the event you want to track.
* **`properties`** (`object`, Optional): Additional key-value pairs related to the event.

### Example [#example-2]

```tsx
await rybbit.event("signup_started", { plan: "pro" });

await rybbit.event("purchase_completed", {
  orderId: "order-123",
  total: 49.99,
  currency: "USD",
});
```

## Error Tracking [#error-tracking]

Capture handled errors with additional context. Error tracking must be enabled in your Rybbit dashboard (Capture Errors) — when disabled, `error()` calls are ignored.

### Syntax [#syntax-3]

```typescript
rybbit.error(error: Error | unknown, properties?: TrackProperties, context?: TrackContext): Promise<void>;
```

Non-`Error` values are converted to an `Error`. The message is truncated to 500 characters and the stack trace to 2,000.

### Example [#example-3]

```tsx
try {
  await processPayment(order);
} catch (error) {
  await rybbit.error(error, { component: "checkout", orderId: order.id });
  showErrorMessage();
}
```

<Callout type="info">
  Unlike the web SDK, the React Native SDK does not automatically capture uncaught exceptions — wrap the code you care about and call `rybbit.error()` yourself.
</Callout>

## User Identification [#user-identification]

Associate events with a user ID and optional traits. The ID is persisted through the configured storage adapter and attached to all subsequent events.

```typescript
rybbit.identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
rybbit.setTraits(traits: Record<string, unknown>): Promise<void>;
rybbit.clearUserId(): Promise<void>;
rybbit.getUserId(): string | null;
```

```tsx
// After login
await rybbit.identify("user_123", { plan: "pro", signupDate: "2026-01-15" });

// Update traits later without changing the ID
await rybbit.setTraits({ plan: "enterprise" });

// After logout
await rybbit.clearUserId();
```

<Callout type="info">
  `setTraits()` throws if no user has been identified yet — call `identify()` first.
</Callout>

## App Lifecycle Events [#app-lifecycle-events]

With `autoTrackAppLifecycle` enabled (the default), the SDK listens to React Native's `AppState` and tracks:

* **`app_open`** — when the app launches in the foreground or returns to the foreground from the background.
* **`app_background`** — when the app leaves the foreground, with a `state` property (`"background"` or `"inactive"`).

Set `autoTrackAppLifecycle: false` in `init()` to disable these events.

## Offline Handling and Retries [#offline-handling-and-retries]

Events that fail to send (e.g., no network) are kept in an in-memory queue, capped at `maxQueueSize` (default 100, oldest dropped first). Queued events are retried when `init()` completes and whenever you call:

```typescript
rybbit.flush(): Promise<void>;
```

<Callout type="warning">
  The retry queue is in-memory only — events still queued when the app is killed are lost.
</Callout>

## Track Context [#track-context]

All tracking methods accept an optional `context` object to override what's sent with that event:

| Field           | Type     | Description                                   |
| :-------------- | :------- | :-------------------------------------------- |
| `appIdentifier` | `string` | Override the hostname for this event.         |
| `pathname`      | `string` | Override the tracked path.                    |
| `querystring`   | `string` | Query string to attach to the event.          |
| `screen`        | `string` | Screen name, used as the path/title fallback. |
| `title`         | `string` | Override the page title.                      |
| `referrer`      | `string` | Referrer value (empty by default on mobile).  |
| `language`      | `string` | Override the detected device locale.          |
| `userAgent`     | `string` | Override the synthetic user agent.            |

Device locale, screen dimensions, and a platform-appropriate user agent (including your `appVersion`) are detected automatically.

## Cleanup [#cleanup]

Removes the `AppState` lifecycle listener. Call it if you tear down the SDK, e.g. in tests or when unmounting your app root.

```typescript
rybbit.cleanup(): void;
```

## Differences from the Web SDK [#differences-from-the-web-sdk]

* **Session replay** and **Web Vitals** are web-only and not available for React Native apps.
* No automatic outbound link, button click, form, or copy tracking (there is no DOM).
* Uncaught errors are not captured automatically — use `rybbit.error()` in your own error boundaries and catch blocks.
* The anonymous visitor ID is generated by the SDK and persisted via your storage adapter, rather than derived from browser fingerprinting.


# JavaScript (Web) (/docs/sdks/web)





## Installation [#installation]

```bash
npm install @rybbit/js
```

```bash
yarn add @rybbit/js
```

## Peer Dependencies [#peer-dependencies]

The SDK has an optional peer dependency for session replay functionality:

```bash
npm install rrweb
```

```bash
yarn add rrweb
```

<Callout type="info">
  The `rrweb` package is only required if you enable session replay in your Rybbit dashboard. The SDK will work without it for all other tracking features.
</Callout>

## Initialization [#initialization]

<Callout type="warning">
  `rybbit.init()` **must** be called once before any other tracking methods (`pageview`, `event`, etc.) can be used. Attempting to call other methods before `init` will result in errors or no tracking.
</Callout>

### Syntax [#syntax]

```typescript
async rybbit.init(config: RybbitConfig): Promise<void>;
```

### Example [#example]

```javascript
import rybbit from "@rybbit/js";

await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
});
```

### Configuration Options [#configuration-options]

#### Required Options [#required-options]

| Option          | Type     | Description                                                                        |
| :-------------- | :------- | :--------------------------------------------------------------------------------- |
| `analyticsHost` | `string` | URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |
| `siteId`        | `string` | The Site ID for your website obtained from your Rybbit instance.                   |

#### Local Configuration Options [#local-configuration-options]

These options are configured in your code and control SDK behavior locally:

| Option                | Type       | Default | Description                                                                                                                                                             |
| :-------------------- | :--------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `debounceDuration`    | `number`   | `500`   | Debounce time in milliseconds for tracking pageviews after route changes. Set to `0` to disable debouncing (track immediately).                                         |
| `skipPatterns`        | `string[]` | `[]`    | Array of path patterns. Pageviews whose path matches any pattern will **not** be tracked. See [Path Matching](#path-matching).                                          |
| `maskPatterns`        | `string[]` | `[]`    | Array of path patterns. For matching pageview paths, the original path will be **replaced** by the pattern itself in tracked data. See [Path Matching](#path-matching). |
| `debug`               | `boolean`  | `false` | Enable detailed logging to the browser console.                                                                                                                         |
| `replayPrivacyConfig` | `object`   | -       | Privacy settings for session replay. See [Session Replay](#session-replay).                                                                                             |

#### Remote Configuration [#remote-configuration]

These settings are controlled through your Rybbit dashboard and cannot be set in the init config:

| Dashboard Setting       | Description                                              | Default |
| :---------------------- | :------------------------------------------------------- | :------ |
| Track Initial Pageview  | Track pageview on initial page load                      | `true`  |
| Track SPA Navigation    | Track pageviews on Single Page Application route changes | `true`  |
| Track URL Parameters    | Include URL query strings in tracked data                | `true`  |
| Track Outbound Links    | Automatically track clicks on external links             | `true`  |
| Track Web Vitals        | Track Core Web Vitals performance metrics                | `false` |
| Capture Errors          | Enable automatic error tracking                          | `false` |
| Session Replay          | Enable session replay recording                          | `false` |
| Track Button Clicks     | Automatically track button click interactions            | `false` |
| Track Copy              | Automatically track copy events                          | `false` |
| Track Form Interactions | Automatically track form submissions and input changes   | `false` |

If fetching settings fails or times out, the SDK uses sensible defaults.

## Tracking Pageviews [#tracking-pageviews]

Pageviews are tracked automatically based on your dashboard settings. This includes the initial page load and subsequent route changes in Single Page Applications (SPAs).

### Syntax [#syntax-1]

```typescript
rybbit.pageview(path?: string);
```

### Parameters [#parameters]

* **`path`** (`string`, Optional):
  * Replaces the detected URL path (`window.location.pathname`) and query string (`window.location.search`) for this specific pageview event.
  * Should start with a `/` (e.g., `/virtual/my-custom-page`).
  * If `path` includes its own query string (e.g., `/virtual/step?id=123`), that query string will be used for the event. If `path` has no query string, the `querystring` property will be empty.
  * `skipPatterns` and `maskPatterns` will be applied to `path`.

### When to Use Manually [#when-to-use-manually]

* **Automatic tracking disabled:** If you disabled automatic pageview tracking in your dashboard.
* **Virtual Pageviews:** In SPAs where a significant view change occurs without a URL change.
* **Specific Timing:** If you need to ensure a pageview is tracked only after certain conditions are met.

### Example [#example-1]

```javascript
// Standard manual pageview (usually not needed if auto-tracking is on)
rybbit.pageview();

// Example: Track a step within a multi-step modal
function openUserDetailsModal(userId, step) {
  // ... logic to open and display the modal step ...
  rybbit.pageview(`/users/${userId}/modal/${step}`);
}
openUserDetailsModal("user-abc", "contact-info");

// Example: Track a virtual pageview with its own query parameters
function showFilteredProductList(category, sortBy) {
   let virtualPathWithQuery = `/products/category/${category}?sort=${sortBy}&view=grid`;
   rybbit.pageview(virtualPathWithQuery);
}
showFilteredProductList("electronics", "price_desc");
```

## Tracking Custom Events [#tracking-custom-events]

Use custom events to track specific user interactions. Examples include button clicks, form submissions, or adding an item to a cart.

### Programmatic Tracking [#programmatic-tracking]

You can trigger events from your JavaScript code.

#### Syntax [#syntax-2]

```typescript
rybbit.event(name: string, properties?: TrackProperties);
```

#### Parameters [#parameters-1]

* **`name`** (`string`, Required): The name of the event you want to track.
* **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values can be a `string`, `number`, `boolean`, or an array of these types.

#### Example [#example-2]

```javascript
// Track a simple button click
document.getElementById("cta-button")?.addEventListener("click", () => {
  rybbit.event("cta_click");
});

// Track adding an item to a shopping cart with properties
function addToCart(item) {
  // ... add item ...
  rybbit.event("add_to_cart", {
    itemId: item.id,
    itemName: item.name,
    price: item.price,
    quantity: 1
  });
}
```

### Declarative Tracking with Data Attributes [#declarative-tracking-with-data-attributes]

The SDK automatically listens for clicks on elements with the `data-rybbit-event` attribute.

* `data-rybbit-event="<event-name>"`: This attribute makes the element trackable. The value is used as the event name.
* `data-rybbit-prop-<property-name>="<value>"`: You can add multiple properties to the event by using this attribute format. The SDK collects all attributes starting with `data-rybbit-prop-` and includes them as key-value pairs in the event data.

#### Example [#example-3]

```html
<button data-rybbit-event="cta_click">Click Me</button>

<button
  data-rybbit-event="add_to_cart"
  data-rybbit-prop-item_id="product-123"
  data-rybbit-prop-item_name="Classic T-Shirt"
  data-rybbit-prop-price="29.99"
>
  Add to Cart
</button>
```

## Tracking Outbound Links [#tracking-outbound-links]

Outbound links (links to external domains) are tracked automatically by default based on your dashboard settings. The SDK attaches a global click listener to capture clicks on `<a>` tags with external `href` attributes.

### Syntax [#syntax-3]

```typescript
rybbit.trackOutbound(url: string, text?: string, target?: string);
```

### Parameters [#parameters-2]

* **`url`** (`string`, Required): The destination URL of the outbound link.
* **`text`** (`string`, Optional): The text content of the link. Defaults to `""`.
* **`target`** (`string`, Optional): The `target` attribute of the link (e.g., `_blank`). Defaults to `_self`.

### When to Use Manually [#when-to-use-manually-1]

* **Automatic tracking disabled:** If you disabled outbound link tracking in your dashboard.
* **Non-anchor elements:** If you trigger navigation to an external site using JavaScript from an element that isn't an `<a>` tag.

### Example [#example-4]

```javascript
// Manually track an outbound click triggered by a button
document.getElementById("external-service-button")?.addEventListener("click", () => {
  let url = "https://external-service.com";
  rybbit.trackOutbound(url, "Visit External Service", "_blank");
  // Optionally navigate after tracking
  window.open(url, "_blank");
});
```

## Error Tracking [#error-tracking]

The SDK can automatically capture JavaScript errors and unhandled promise rejections. This feature must be enabled in your Rybbit dashboard.

### Automatic Error Capture [#automatic-error-capture]

When enabled in your dashboard, the SDK will automatically track:

* Uncaught exceptions (`window.error` events)
* Unhandled promise rejections (`window.unhandledrejection` events)

### Manual Error Capture [#manual-error-capture]

You can manually capture errors with additional context:

#### Syntax [#syntax-4]

```typescript
rybbit.error(error: Error | ErrorEvent, context?: TrackProperties);
```

#### Parameters [#parameters-3]

* **`error`** (`Error | ErrorEvent`, Required): The error object to capture.
* **`context`** (`object`, Optional): Additional context to include with the error.

#### Example [#example-5]

```javascript
try {
  // Some risky operation
  processPayment(orderData);
} catch (error) {
  rybbit.error(error, {
    component: "checkout",
    orderId: "order-123",
    userId: currentUser.id
  });
  // Handle error in your UI
  showErrorMessage("Payment failed");
}

// Capture error from async operation
async function fetchUserData(userId) {
  try {
    const response = await fetch(`/api/users/${userId}`);
    return await response.json();
  } catch (error) {
    rybbit.error(error, {
      endpoint: "/api/users",
      userId: userId
    });
    throw error;
  }
}
```

<Callout type="info">
  Manual error capture only works when error tracking is enabled in your dashboard settings. If it's disabled, calling `error()` will log a warning.
</Callout>

## Session Replay [#session-replay]

Session replay records user interactions on your website, allowing you to watch how users navigate and interact with your site. This feature requires the `rrweb` peer dependency.

### Installation [#installation-1]

```bash
npm install rrweb
```

### Enabling Session Replay [#enabling-session-replay]

Session replay must be enabled in your Rybbit dashboard under. Once enabled, recording starts automatically when the SDK initializes.

### Manual Controls [#manual-controls]

You can manually start, stop, and check the status of session replay:

```typescript
// Start recording (only works if enabled in dashboard)
rybbit.startSessionReplay();

// Stop recording
rybbit.stopSessionReplay();

// Check if currently recording
const isRecording = rybbit.isSessionReplayActive();
if (isRecording) {
  console.log("Session is being recorded");
}
```

### Privacy Configuration [#privacy-configuration]

Session replay includes privacy-focused defaults and configuration options:

```javascript
await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  replayPrivacyConfig: {
    maskAllInputs: true, // Mask all input values (default: true)
    maskTextSelectors: [
      ".sensitive-data",  // Mask text in elements with this class
      "#credit-card"      // Mask specific element IDs
    ]
  }
});
```

#### Privacy Config Options [#privacy-config-options]

| Option              | Type                | Description                                                             |
| :------------------ | :------------------ | :---------------------------------------------------------------------- |
| `maskAllInputs`     | `boolean`           | Mask all input values (default: `true`)                                 |
| `maskTextSelectors` | `string[]`          | CSS selectors for elements whose text should be masked                  |
| `blockClass`        | `string`            | CSS class name to block elements from recording (default: `rr-block`)   |
| `blockSelector`     | `string`            | CSS selector to block elements from recording                           |
| `ignoreClass`       | `string`            | CSS class name to ignore elements from recording (default: `rr-ignore`) |
| `ignoreSelector`    | `string`            | CSS selector to ignore elements from recording                          |
| `maskTextClass`     | `string`            | CSS class name to mask text content (default: `rr-mask`)                |
| `collectFonts`      | `boolean`           | Whether to collect font information (default: `true`)                   |
| `slimDOMOptions`    | `object \| boolean` | Options to reduce DOM snapshot size                                     |

## User Identification [#user-identification]

You can associate tracking events with a specific user ID and optional traits. The ID is persisted in `localStorage` and will be attached to all subsequent tracking events for that user.

### `identify` [#identify]

Assigns a user ID with optional traits.

```typescript
rybbit.identify(userId: string, traits?: Record<string, unknown>);
```

**Parameters:**

* **`userId`** (`string`, Required): The user ID to associate with tracking events.
* **`traits`** (`object`, Optional): An object containing user attributes/properties.

**Example:**

```javascript
// After a user logs in
rybbit.identify("user-xzy-123");

// With traits
rybbit.identify("user-xzy-123", {
  email: "user@example.com",
  plan: "premium",
  signupDate: "2024-01-15"
});
```

### `setTraits` [#settraits]

Updates traits for the currently identified user without changing the user ID.

```typescript
rybbit.setTraits(traits: Record<string, unknown>);
```

**Example:**

```javascript
// Update user traits after they upgrade
rybbit.setTraits({
  plan: "enterprise",
  upgradeDate: "2024-03-01"
});
```

### `clearUserId` [#clearuserid]

Clears the stored user ID.

```typescript
rybbit.clearUserId();
```

**Example:**

```javascript
// When a user logs out
rybbit.clearUserId();
```

### `getUserId` [#getuserid]

Retrieves the currently stored user ID.

```typescript
rybbit.getUserId(): string | null;
```

**Example:**

```javascript
let currentUserId = rybbit.getUserId();
console.log("Current Rybbit User ID:", currentUserId);
```

## Page Change Callbacks [#page-change-callbacks]

Register callbacks that execute when the page or route changes. This is useful for integrating with third-party tools or triggering custom logic on navigation.

### Syntax [#syntax-5]

```typescript
rybbit.onPageChange(callback: (newPath: string, previousPath: string) => void): () => void;
```

### Parameters [#parameters-4]

* **`callback`** (`function`, Required): Function to execute on page change. Receives:
  * `newPath`: The new pathname
  * `previousPath`: The previous pathname

### Returns [#returns]

Returns an unsubscribe function to remove the callback.

### Example [#example-6]

```javascript
// Register a callback
const unsubscribe = rybbit.onPageChange((newPath, previousPath) => {
  console.log(`Navigated from ${previousPath} to ${newPath}`);

  // Example: Track scroll position reset
  window.scrollTo(0, 0);
});

// Later, to remove the callback
unsubscribe();

// Example: Multiple callbacks can be registered
rybbit.onPageChange((newPath) => {
  // Update page title
  document.title = `${newPath} - My Site`;
});

rybbit.onPageChange((newPath, previousPath) => {
  // Log navigation for debugging
  if (process.env.NODE_ENV === 'development') {
    console.log('Navigation:', { from: previousPath, to: newPath });
  }
});
```

<Callout type="info">
  Callbacks are only triggered when the pathname actually changes. Multiple calls to the same path won't trigger callbacks repeatedly.
</Callout>

## Opting Out [#opting-out]

Users can opt out of all tracking by setting a flag in `localStorage` or on the `window` object. When opted out, all tracking calls are silently ignored.

```javascript
// Opt out via localStorage (persists across sessions)
localStorage.setItem("disable-rybbit", "true");

// Opt out via window flag (current session only)
window.__RYBBIT_OPTOUT__ = true;
```

To re-enable tracking, remove the localStorage item and reload the page:

```javascript
localStorage.removeItem("disable-rybbit");
```

## Cleanup [#cleanup]

In Single Page Applications or other dynamic environments, you may need to manually clean up the listeners that the SDK sets up.

### Syntax [#syntax-6]

```typescript
rybbit.cleanup();
```

### What Gets Cleaned Up [#what-gets-cleaned-up]

* SPA route change listeners (`popstate`, `hashchange`)
* Outbound link click listeners
* Data attribute click listeners
* Error tracking listeners
* Session replay recording
* Page change callbacks
* Resets initialization state

### Example [#example-7]

```javascript
// In React
useEffect(() => {
  rybbit.init({
    analyticsHost: "https://app.rybbit.io/api",
    siteId: "1",
  });

  return () => {
    rybbit.cleanup();
  };
}, []);
```

## Path Matching [#path-matching]

These options allow you to control which page paths are tracked and how they appear in your analytics data using wildcard patterns.

### Wildcards [#wildcards]

* `*`: Matches any sequence of characters **except** the forward slash (`/`). Useful for matching single path segments.
* `**`: Matches any sequence of characters **including** the forward slash (`/`). Useful for matching multiple path segments.

### Regex Patterns [#regex-patterns]

For more advanced matching, you can use raw regular expressions by prefixing the pattern with `re:`:

```javascript
skipPatterns: [
  "re:^/users/\\d+/profile$",  // Match numeric user IDs only
  "re:^/api/v[0-9]+/"          // Match any API version prefix
]
```

### `skipPatterns` [#skippatterns]

If a page's path matches any pattern in `skipPatterns`, the pageview for that path will **not** be sent.

**Examples:**

* `"/admin/*"`: Skips `/admin/login`, `/admin/users`, but **not** `/admin/settings/profile`.
* `"/admin/**"`: Skips `/admin/login`, `/admin/users`, *and* `/admin/settings/profile`.
* `"/users/*/profile"`: Skips `/users/123/profile`, `/users/abc/profile`, but **not** `/users/123/settings`.

```javascript
// Example skipPatterns in init
await rybbit.init({
  // ... other options
  skipPatterns: [
    "/admin/**",        // Skip all admin sections
    "/debug",           // Skip exact /debug path
    "/users/*/settings" // Skip settings page for any user
  ]
});
```

### `maskPatterns` [#maskpatterns]

If a page's path matches a pattern in `maskPatterns`, the pageview **will** be sent, but the `pathname` will be **replaced** by the pattern string itself. This is useful for grouping similar pages or hiding sensitive IDs.

<Callout type="warning">
  If a path matches both a `skipPatterns` and a `maskPatterns` pattern, **skipping takes priority**.
</Callout>

**Examples:**

* Pattern: `"/users/*/profile"`
  * `/users/123/profile` is tracked as `pathname: "/users/*/profile"`.
* Pattern: `"/products/**"`
  * `/products/electronics/tv-123` is tracked as `pathname: "/products/**"`.

```javascript
// Example maskPatterns in init
await rybbit.init({
  // ... other options
  maskPatterns: [
    "/users/*/profile",  // Group all user profile views
    "/orders/*"          // Mask specific order IDs
  ]
});
```


# Custom Nginx setup (/docs/self-hosting-guides/custom-nginx)





This guide shows you how to set up Rybbit with your own Nginx installation instead of using the built-in Caddy server.

## Prerequisites [#prerequisites]

* Existing Nginx installation
* SSL certificates (Let's Encrypt recommended)
* Domain pointed to your server
* Rybbit running with `--no-webserver` flag

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Run Rybbit without Caddy [#run-rybbit-without-caddy]

    First, set up Rybbit to expose ports without the built-in webserver:

    ```bash
    ./setup.sh your.domain.name --no-webserver
    ```

    Optionally, include a Mapbox token for globe visualizations:

    ```bash
    ./setup.sh your.domain.name --no-webserver --mapbox-token YOUR_MAPBOX_TOKEN
    ```

    This will expose:

    * Backend service on port 3001
    * Client service on port 3002
  </Step>

  <Step>
    ### Configure Nginx [#configure-nginx]

    Create or update your Nginx configuration file (usually in `/etc/nginx/sites-available/`):

    ```nginx
    server {
        listen 80;
        server_name your.domain.name;
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name your.domain.name;

        # SSL configuration (using Let's Encrypt)
        ssl_certificate /etc/letsencrypt/live/your.domain.name/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/your.domain.name/privkey.pem;
        
        # Modern SSL configuration
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
        ssl_prefer_server_ciphers off;
        
        # Security headers
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-XSS-Protection "1; mode=block" always;

        # Backend service
        location ~ ^/(api|\.well-known)/.*$ {
            proxy_pass http://localhost:3001;
            proxy_set_header Host $host;
            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_set_header X-Forwarded-Host $server_name;
            
            # Timeouts
            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
        }

        # Client service
        location / {
            proxy_pass http://localhost:3002;
            proxy_set_header Host $host;
            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_set_header X-Forwarded-Host $server_name;
            
            # Timeouts
            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
        }
    }
    ```
  </Step>

  <Step>
    ### Enable the Site [#enable-the-site]

    Enable your Nginx configuration:

    ```bash
    # Create symlink to enable the site
    sudo ln -s /etc/nginx/sites-available/your-site /etc/nginx/sites-enabled/

    # Test the configuration
    sudo nginx -t

    # Reload Nginx
    sudo systemctl reload nginx
    ```
  </Step>

  <Step>
    ### Verify Setup [#verify-setup]

    Check that everything is working:

    ```bash
    # Check Nginx status
    sudo systemctl status nginx

    # Check Rybbit services
    docker compose ps

    # Test the website
    curl -I https://your.domain.name
    ```
  </Step>
</Steps>

## SSL Certificate Setup with Certbot [#ssl-certificate-setup-with-certbot]

If you need to set up SSL certificates with Let's Encrypt:

<Steps>
  <Step>
    ### Install Certbot [#install-certbot]

    ```bash
    # Ubuntu/Debian
    sudo apt update
    sudo apt install certbot python3-certbot-nginx

    # CentOS/RHEL
    sudo yum install certbot python3-certbot-nginx
    ```
  </Step>

  <Step>
    ### Obtain Certificate [#obtain-certificate]

    ```bash
    sudo certbot --nginx -d your.domain.name
    ```
  </Step>

  <Step>
    ### Auto-renewal [#auto-renewal]

    Set up automatic renewal:

    ```bash
    # Test renewal
    sudo certbot renew --dry-run

    # Check existing cron job
    sudo crontab -l
    ```

    Certbot usually sets up auto-renewal automatically, but you can add this cron job if needed:

    ```bash
    0 12 * * * /usr/bin/certbot renew --quiet
    ```
  </Step>
</Steps>

## Custom Ports [#custom-ports]

If you need to use custom ports for Rybbit:

```bash
./setup.sh your.domain.name --no-webserver --backend-port 8080 --client-port 8081

# With Mapbox token
./setup.sh your.domain.name --no-webserver --backend-port 8080 --client-port 8081 --mapbox-token YOUR_MAPBOX_TOKEN
```

Update your Nginx configuration accordingly:

```nginx
location /api/ {
    proxy_pass http://localhost:8080;  # Custom backend port
    # ... rest of config
}

location / {
    proxy_pass http://localhost:8081;  # Custom client port
    # ... rest of config
}
```

## Troubleshooting [#troubleshooting]

### Common Issues [#common-issues]

**502 Bad Gateway**: Check if Rybbit services are running:

```bash
docker compose ps
docker compose logs
```

**SSL Certificate Issues**: Verify certificate paths:

```bash
sudo certbot certificates
```

**Permission Denied**: Check Nginx error logs:

```bash
sudo tail -f /var/log/nginx/error.log
```

### Logs [#logs]

Monitor logs for debugging:

```bash
# Nginx access logs
sudo tail -f /var/log/nginx/access.log

# Nginx error logs
sudo tail -f /var/log/nginx/error.log

# Rybbit logs
docker compose logs -f
```


# Nginx Proxy Manager (NPM) setup (/docs/self-hosting-guides/nginx-proxy-manager)





This guide shows you how to set up Rybbit with Nginx Proxy Manager without exposing ports directly to the host.

## Prerequisites [#prerequisites]

* [Nginx Proxy Manager](https://nginxproxymanager.com) already running
* Basic knowledge of Docker networks
* Domain name pointed to your server

<Callout type="info">
  This setup assumes you have NPM running and are capable of creating SSL certificates. You can also use any other reverse proxy as long as you can put it on the same Docker network as Rybbit.
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Create Custom Docker Compose [#create-custom-docker-compose]

    Create a new directory for your Rybbit installation and create a `docker-compose.yml` file:

    ```yaml
    services:
      rybbit_clickhouse:
        image: clickhouse/clickhouse-server:26.3.17.4
        container_name: rybbit_clickhouse
        volumes:
          - ./clickhouse-data:/var/lib/clickhouse
        configs:
          - source: clickhouse_network
            target: /etc/clickhouse-server/config.d/network.xml
          - source: clickhouse_logging
            target: /etc/clickhouse-server/config.d/logging_rules.xml
          # Profile (user-level) settings are only read from users.d, not config.d
          - source: clickhouse_user_settings
            target: /etc/clickhouse-server/users.d/user_settings.xml
        environment:
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        networks:
          - internal

      rybbit_postgres:
        image: postgres:17.4
        container_name: rybbit_postgres
        environment:
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
        volumes:
          - ./postgres-data:/var/lib/postgresql/data
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        networks:
          - internal

      rybbit_redis:
        image: redis:8.6.4-alpine
        container_name: rybbit_redis
        volumes:
          - ./redis-data:/data
        healthcheck:
          test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 5s
        restart: unless-stopped
        command:
          - redis-server
          - --requirepass
          - ${REDIS_PASSWORD:-changeme}
          - --appendonly
          - "yes"
          - --appendfsync
          - everysec
          - --maxmemory-policy
          - noeviction
        networks:
          - internal

      rybbit_backend:
        image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}
        container_name: rybbit_backend
        environment:
          - NODE_ENV=production
          - CLICKHOUSE_HOST=http://rybbit_clickhouse:8123
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
          - POSTGRES_HOST=rybbit_postgres
          - POSTGRES_PORT=5432
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - REDIS_HOST=rybbit_redis
          - REDIS_PORT=6379
          - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
          - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
          - BASE_URL=${BASE_URL}
          - DISABLE_SIGNUP=${DISABLE_SIGNUP}
          - MAPBOX_TOKEN=${MAPBOX_TOKEN}
        depends_on:
          rybbit_clickhouse:
            condition: service_healthy
          rybbit_postgres:
            condition: service_healthy
          rybbit_redis:
            condition: service_healthy
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3001/api/health"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        networks:
          - internal
          - npm_proxy

      rybbit_client:
        image: ghcr.io/rybbit-io/rybbit-client:${IMAGE_TAG:-latest}
        container_name: rybbit_client
        environment:
          - NODE_ENV=production
          - NEXT_PUBLIC_BACKEND_URL=${BASE_URL}
          - NEXT_PUBLIC_DISABLE_SIGNUP=${DISABLE_SIGNUP}
        depends_on:
          - rybbit_backend
        restart: unless-stopped
        networks:
          - internal
          - npm_proxy

    networks:
      internal:
        driver: bridge
      npm_proxy:
        external: true

    configs:
      clickhouse_network:
        content: |
          <clickhouse>
              <listen_host>0.0.0.0</listen_host>
          </clickhouse>

      clickhouse_logging:
        content: |
          <clickhouse>
            <logger>
                <level>warning</level>
                <console>true</console>
            </logger>
            <query_thread_log remove="remove"/>
            <query_log remove="remove"/>
            <text_log remove="remove"/>
            <trace_log remove="remove"/>
            <metric_log remove="remove"/>
            <asynchronous_metric_log remove="remove"/>
            <session_log remove="remove"/>
            <part_log remove="remove"/>
            <latency_log remove="remove"/>
            <processors_profile_log remove="remove"/>
          </clickhouse>

      clickhouse_user_settings:
        content: |
          <clickhouse>
            <profiles>
              <default>
                <enable_json_type>1</enable_json_type>
                <!-- 26.3+ enables async_insert by default; the backend already
                     batches app-side, so keep inserts synchronous -->
                <async_insert>0</async_insert>
                <log_queries>0</log_queries>
                <log_query_threads>0</log_query_threads>
                <log_processors_profiles>0</log_processors_profiles>
              </default>
            </profiles>
          </clickhouse>
    ```
  </Step>

  <Step>
    ### Configure Environment [#configure-environment]

    Create a `.env` file in the same directory:

    ```bash
    # Required: Your domain and base URL
    DOMAIN_NAME=your.domain.com
    BASE_URL=https://your.domain.com

    # Required: Authentication secret (generate a random 32+ character string)
    BETTER_AUTH_SECRET=your_generated_secret_here

    # Optional: Disable new user signups after creating admin account
    DISABLE_SIGNUP=false

    # Optional but recommended: Mapbox token for globe visualizations
    MAPBOX_TOKEN=your_mapbox_token

    # Optional: Custom image tag
    IMAGE_TAG=latest
    ```

    <Callout type="info">
      Generate a secure `BETTER_AUTH_SECRET` using: `openssl rand -hex 32`
    </Callout>
  </Step>

  <Step>
    ### Setup Docker Network [#setup-docker-network]

    Create the external network that NPM uses (if it doesn't exist):

    ```bash
    docker network create npm_proxy
    ```

    Make sure your NPM container is connected to this network:

    ```bash
    # Check if NPM is on the network
    docker network inspect npm_proxy

    # If needed, connect NPM to the network
    docker network connect npm_proxy <npm_container_name>
    ```
  </Step>

  <Step>
    ### Start Services [#start-services]

    Start all Rybbit services:

    ```bash
    docker compose up -d
    ```

    Verify all services are running:

    ```bash
    docker compose ps
    ```
  </Step>

  <Step>
    ### Configure NPM [#configure-npm]

    In your Nginx Proxy Manager interface:

    1. **Create Proxy Host**:
       * Domain Names: `your.domain.com`
       * Scheme: `http`
       * Forward Hostname/IP: `rybbit_client`
       * Forward Port: `3002`
       * Enable "Cache Assets", "Block Common Exploits", "Websockets Support"

    2. **Add Custom Location**:
       * Location: `/api`
       * Scheme: `http`
       * Forward Hostname/IP: `rybbit_backend`
       * Forward Port: `3001`

    3. **Advanced Configuration** (in the custom location):
       ```nginx
       location /api/ {
           proxy_pass http://rybbit_backend:3001;
           proxy_set_header Host $host;
           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;
       }
       ```

    4. **SSL Configuration**:
       * Enable SSL
       * Request a new SSL certificate with Let's Encrypt
       * Enable "Force SSL" and "HTTP/2 Support"
  </Step>

  <Step>
    ### Access Rybbit [#access-rybbit]

    Navigate to `https://your.domain.com` and create your admin account.
  </Step>
</Steps>

## Alternative Proxy Configurations [#alternative-proxy-configurations]

### Traefik [#traefik]

If you're using Traefik instead, add these labels to your services:

```yaml
services:
  rybbit_backend:
    # ... existing config
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && PathPrefix(`/api`)"
      - "traefik.http.routers.rybbit-api.tls.certresolver=letsencrypt"
      - "traefik.http.services.rybbit-api.loadbalancer.server.port=3001"
      - "traefik.docker.network=traefik_proxy"
  
  rybbit_client:
    # ... existing config
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.rybbit-client.rule=Host(`your.domain.com`)"
      - "traefik.http.routers.rybbit-client.tls.certresolver=letsencrypt"
      - "traefik.http.services.rybbit-client.loadbalancer.server.port=3002"
      - "traefik.docker.network=traefik_proxy"

networks:
  traefik_proxy:
    external: true
```

### Cloudflare Tunnel [#cloudflare-tunnel]

For Cloudflare Tunnel, create a tunnel configuration:

```yaml
tunnel: your-tunnel-id
credentials-file: /path/to/credentials.json

ingress:
  - hostname: your.domain.com
    path: /api
    service: http://rybbit_backend:3001
  - hostname: your.domain.com
    service: http://rybbit_client:3002
  - service: http_status:404
```

## Troubleshooting [#troubleshooting]

### Common Issues [#common-issues]

**NPM can't reach containers**:

* Verify both NPM and Rybbit are on the same network
* Check container names match the proxy configuration

**SSL certificate issues**:

* Ensure domain is pointed to your server
* Check NPM logs for certificate generation errors

**502 Bad Gateway**:

* Verify Rybbit services are healthy: `docker compose ps`
* Check container logs: `docker compose logs`

### Networking [#networking]

Check network connectivity:

```bash
# List all networks
docker network ls

# Inspect the npm_proxy network
docker network inspect npm_proxy

# Check which containers are connected
docker ps --format "table {{.Names}}\t{{.Networks}}"
```

### Logs [#logs]

Monitor logs for debugging:

```bash
# Rybbit services
docker compose logs -f

# Specific service
docker compose logs -f rybbit_backend

# NPM logs (adjust container name)
docker logs -f nginx-proxy-manager
```

<Callout type="warning">
  Remember to regularly backup your data volumes (`clickhouse-data` and `postgres-data`) and your `.env` file.
</Callout>


# Pangolin setup (/docs/self-hosting-guides/pangolin)







This guide shows you how to set up Rybbit with [Pangolin](https://github.com/fosrl/pangolin), a self-hosted reverse proxy, using a Newt container inside the Docker Compose stack. This approach avoids exposing ports directly on your host network.

## Prerequisites [#prerequisites]

* [Pangolin](https://github.com/fosrl/pangolin) already running and accessible (e.g. `https://pangolin.yourdomain.com`)
* A Newt ID and Newt Secret from your Pangolin instance
* A domain name pointed to your Pangolin server (e.g. `tracking.yourdomain.com`)
* Docker and Docker Compose installed

<Callout type="warning">
  You **must** generate a proper `BETTER_AUTH_SECRET` before starting. Without a valid 32+ character secret, you will not be able to create organizations or log in. Generate one with: `openssl rand -hex 32`
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Configure Environment Variables [#configure-environment-variables]

    Create a `.env` file in your Rybbit directory:

    ```bash
    # Required: Your domain and base URL
    DOMAIN_NAME=tracking.yourdomain.com
    BASE_URL=https://tracking.yourdomain.com

    # Required: Authentication secret (must be 32+ characters)
    # Generate with: openssl rand -hex 32
    BETTER_AUTH_SECRET=your_generated_secret_here

    # Required: Disable built-in webserver since Pangolin handles routing
    USE_WEBSERVER=false

    # ClickHouse configuration
    CLICKHOUSE_DB=analytics
    CLICKHOUSE_USER=default
    CLICKHOUSE_PASSWORD=changeme

    # PostgreSQL configuration
    POSTGRES_DB=analytics
    POSTGRES_USER=changeme
    POSTGRES_PASSWORD=changeme

    # Redis configuration
    REDIS_PASSWORD=changeme

    # Ports in host:container format (Pangolin needs it like this)
    HOST_BACKEND_PORT=3001:3001
    HOST_CLIENT_PORT=3002:3002

    # Optional: Disable new user signups after creating admin account
    # DISABLE_SIGNUP=true

    # Optional: Mapbox token for globe visualizations
    # MAPBOX_TOKEN=your_mapbox_token
    ```

    <Callout type="info">
      The `HOST_BACKEND_PORT` and `HOST_CLIENT_PORT` values use the `host:container` format without binding to `127.0.0.1`. This is intentional — the Newt container inside the Docker network handles routing, so the ports do not need to be exposed to your host. Even if you already run services on ports 3001/3002 on your host, there will be no conflict.
    </Callout>
  </Step>

  <Step>
    ### Create Docker Compose File [#create-docker-compose-file]

    Create a `docker-compose.yml` file in the same directory. This includes a Newt container that connects Pangolin to your Rybbit services:

    ```yaml
    services:
      newt:
        image: fosrl/newt
        container_name: newt-rybbit
        restart: unless-stopped
        environment:
          - PANGOLIN_ENDPOINT=https://pangolin.yourdomain.com
          - NEWT_ID=your_newt_id
          - NEWT_SECRET=your_newt_secret

      clickhouse:
        container_name: clickhouse
        image: clickhouse/clickhouse-server:26.3.17.4
        volumes:
          - clickhouse-data:/var/lib/clickhouse
        configs:
          - source: clickhouse_network
            target: /etc/clickhouse-server/config.d/network.xml
          - source: clickhouse_logging
            target: /etc/clickhouse-server/config.d/logging_rules.xml
          # Profile (user-level) settings are only read from users.d, not config.d
          - source: clickhouse_user_settings
            target: /etc/clickhouse-server/users.d/user_settings.xml
        environment:
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        ports:
          - "8123:8123"

      postgres:
        image: postgres:17.4
        container_name: postgres
        environment:
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
        volumes:
          - postgres-data:/var/lib/postgresql/data
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        ports:
          - "5432:5432"

      redis:
        image: redis:8.6.4-alpine
        container_name: redis
        volumes:
          - redis-data:/data
        healthcheck:
          test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 5s
        restart: unless-stopped
        command:
          - redis-server
          - --requirepass
          - ${REDIS_PASSWORD:-changeme}
          - --appendonly
          - "yes"
          - --appendfsync
          - everysec
          - --maxmemory-policy
          - noeviction

      backend:
        image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}
        container_name: backend
        ports:
          - "${HOST_BACKEND_PORT:-127.0.0.1:3001:3001}"
        environment:
          - NODE_ENV=production
          - CLICKHOUSE_HOST=http://clickhouse:8123
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
          - POSTGRES_HOST=postgres
          - POSTGRES_PORT=5432
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - REDIS_HOST=redis
          - REDIS_PORT=6379
          - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
          - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
          - BASE_URL=${BASE_URL}
          - DISABLE_SIGNUP=${DISABLE_SIGNUP}
          - DISABLE_TELEMETRY=${DISABLE_TELEMETRY}
          - MAPBOX_TOKEN=${MAPBOX_TOKEN}
        depends_on:
          clickhouse:
            condition: service_healthy
          postgres:
            condition: service_started
          redis:
            condition: service_healthy
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3001/api/health"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped

      client:
        image: ghcr.io/rybbit-io/rybbit-client:${IMAGE_TAG:-latest}
        container_name: client
        ports:
          - "${HOST_CLIENT_PORT:-127.0.0.1:3002:3002}"
        environment:
          - NODE_ENV=production
          - NEXT_PUBLIC_BACKEND_URL=${BASE_URL}
          - NEXT_PUBLIC_DISABLE_SIGNUP=${DISABLE_SIGNUP}
        depends_on:
          - backend
        restart: unless-stopped

    volumes:
      clickhouse-data:
      postgres-data:
      redis-data:

    configs:
      clickhouse_network:
        content: |
          <clickhouse>
              <listen_host>0.0.0.0</listen_host>
          </clickhouse>

      clickhouse_logging:
        content: |
          <clickhouse>
            <logger>
                <level>warning</level>
                <console>true</console>
            </logger>
            <query_thread_log remove="remove"/>
            <query_log remove="remove"/>
            <text_log remove="remove"/>
            <trace_log remove="remove"/>
            <metric_log remove="remove"/>
            <asynchronous_metric_log remove="remove"/>
            <session_log remove="remove"/>
            <part_log remove="remove"/>
            <latency_log remove="remove"/>
            <processors_profile_log remove="remove"/>
          </clickhouse>

      clickhouse_user_settings:
        content: |
          <clickhouse>
            <profiles>
              <default>
                <enable_json_type>1</enable_json_type>
                <!-- 26.3+ enables async_insert by default; the backend already
                     batches app-side, so keep inserts synchronous -->
                <async_insert>0</async_insert>
                <log_queries>0</log_queries>
                <log_query_threads>0</log_query_threads>
                <log_processors_profiles>0</log_processors_profiles>
              </default>
            </profiles>
          </clickhouse>
    ```

    <Callout type="info">
      The `newt` service runs inside the same Docker network as your other containers. It connects to your Pangolin instance and routes traffic to `backend` and `client` by their container hostnames — no host port exposure needed for Pangolin to reach them.
    </Callout>
  </Step>

  <Step>
    ### Start Services [#start-services]

    Start all services:

    ```bash
    docker compose up -d
    ```

    Verify everything is running:

    ```bash
    docker compose ps
    ```

    Check that the backend is healthy:

    ```bash
    docker compose logs backend
    ```
  </Step>

  <Step>
    ### Configure Pangolin [#configure-pangolin]

    In your Pangolin dashboard, create a new site for your Rybbit domain and configure two resources:

    1. **Client resource** — routes the root domain to the Rybbit frontend:
       * Target: `client` (the Docker container hostname)
       * Port: `3002`

    2. **Backend resource** — routes `/api` traffic to the Rybbit backend:
       * Target: `backend` (the Docker container hostname)
       * Port: `3001`

    For both resources, add these custom headers in the Pangolin configuration:

    | Header              | Value                     |
    | ------------------- | ------------------------- |
    | `X-Forwarded-Proto` | `https`                   |
    | `X-Forwarded-Host`  | `tracking.yourdomain.com` |

        <img alt="Pangolin dashboard configuration" src="__img0" />

    <Callout type="warning">
      The `X-Forwarded-Proto` and `X-Forwarded-Host` headers are critical. Without them, API requests from the client to the backend will fail. This is the most common source of issues with this setup.
    </Callout>

    <Callout type="info">
      You do **not** need to enable "Advanced Mode" in Pangolin. The standard configuration with the correct headers is sufficient.
    </Callout>
  </Step>

  <Step>
    ### Access Rybbit [#access-rybbit]

    Navigate to `https://tracking.yourdomain.com` and create your admin account.

    If you see 404 errors on `/api` routes, double-check that:

    * Your `BETTER_AUTH_SECRET` is set and is at least 32 characters
    * The `X-Forwarded-Proto` and `X-Forwarded-Host` headers are configured in Pangolin
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

### Cannot create organizations or log in [#cannot-create-organizations-or-log-in]

This is almost always caused by a missing or invalid `BETTER_AUTH_SECRET`. Generate a proper secret:

```bash
openssl rand -hex 32
```

Add it to your `.env` file and restart the services:

```bash
docker compose down && docker compose up -d
```

### 404 errors on API routes [#404-errors-on-api-routes]

Verify that Pangolin is forwarding the correct headers. The `X-Forwarded-Proto` header must be `https` and `X-Forwarded-Host` must match your domain. Without these, the backend cannot properly handle requests.

### Backend health check failing [#backend-health-check-failing]

Check the backend logs for errors:

```bash
docker compose logs -f backend
```

Ensure ClickHouse and PostgreSQL are healthy:

```bash
docker compose ps
```

### Newt not connecting to Pangolin [#newt-not-connecting-to-pangolin]

Verify your Newt credentials and Pangolin endpoint:

```bash
docker compose logs -f newt-rybbit
```

Make sure `PANGOLIN_ENDPOINT`, `NEWT_ID`, and `NEWT_SECRET` are correct in your `docker-compose.yml`.

## Video Reference [#video-reference]

For a visual walkthrough of setting up Rybbit with Pangolin, see the official Pangolin YouTube guide:

<iframe width="560" height="315" src="https://www.youtube.com/embed/zk-ZhkNdyC8?start=5" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />


# Advanced self-hosting (/docs/self-hosting-guides/self-hosting-advanced)





This guide covers advanced configuration options for self-hosting Rybbit.

## Setup Script Options [#setup-script-options]

The setup script supports several options:

```bash
./setup.sh <domain_name> [options]
```

Available options:

* `--no-webserver`: Disable the built-in Caddy webserver
* `--backend-port <port>`: Set custom host port for backend (default: 3001)
* `--client-port <port>`: Set custom host port for client (default: 3002)
* `--mapbox-token <token>`: Set Mapbox API token (optional but recommended for globe visualizations)
* `--help`: Show help message

Examples:

```bash
# With Mapbox token
./setup.sh tracking.example.com --mapbox-token YOUR_MAPBOX_TOKEN

# Custom ports with built-in webserver
./setup.sh tracking.example.com --backend-port 8080 --client-port 8081

# Custom ports with your own webserver
./setup.sh tracking.example.com --no-webserver --backend-port 8080 --client-port 8081
```

<Callout type="info">
  When you specify custom ports, only the host port mapping changes. Inside the Docker containers, the services still use ports 3001 and 3002.
</Callout>

## Using Your Own Web Server [#using-your-own-web-server]

If you prefer to use your own web server instead of the built-in Caddy server, you can use the `--no-webserver` flag:

```bash
./setup.sh your.domain.name --no-webserver
```

This will:

* Not start the Caddy container
* Expose the backend service on host port 3001 (or your custom port)
* Expose the client service on host port 3002 (or your custom port)

<Callout type="info">
  For detailed configuration examples with Nginx, Traefik, NPM, and other reverse proxies, see our [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) guide.
</Callout>

## Environment Variables [#environment-variables]

The setup script creates a minimal `.env` file with only the essential variables:

```bash
DOMAIN_NAME=your.domain.com
BASE_URL=https://your.domain.com
BETTER_AUTH_SECRET=generated_secret
DISABLE_SIGNUP=false
```

Optional variables that can be added:

```bash
# Mapbox token for 3D map visualizations
MAPBOX_TOKEN=your_mapbox_token

# Database configuration (uses defaults if not specified)
CLICKHOUSE_PASSWORD=frog
POSTGRES_USER=frog
POSTGRES_PASSWORD=frog
POSTGRES_DB=analytics
CLICKHOUSE_DB=analytics

# Custom image tags
IMAGE_TAG=latest

# Port mapping (only needed for custom ports or --no-webserver)
HOST_BACKEND_PORT="3001:3001"
HOST_CLIENT_PORT="3002:3002"
```


# Manual Docker Compose setup (/docs/self-hosting-guides/self-hosting-manual)





This guide is for users who want to manually set up Rybbit using Docker Compose without the setup script. This is useful if you already have a reverse proxy setup (like Nginx, Traefik, or Coolify), or if you want more control over the configuration.

## Prerequisites [#prerequisites]

* Docker and Docker Compose installed
* A domain name pointed to your server
* Basic knowledge of Docker and environment variables

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Clone the Repository [#clone-the-repository]

    ```bash
    git clone https://github.com/rybbit-io/rybbit.git
    cd rybbit
    ```
  </Step>

  <Step>
    ### Create Environment File [#create-environment-file]

    Create a `.env` file in the root directory with the following content:

    ```bash
    # Required: Your domain and base URL
    DOMAIN_NAME=your.domain.com
    BASE_URL=https://your.domain.com

    # Required: Authentication secret (generate a random 32+ character string)
    BETTER_AUTH_SECRET=your-very-long-random-secret-string-here

    # Optional: Disable new user signups after creating admin account
    DISABLE_SIGNUP=false

    # Optional but recommended: Mapbox token for globe visualizations
    MAPBOX_TOKEN=your_mapbox_token

    # Optional: Custom ports (only needed if you want different ports)
    # HOST_BACKEND_PORT="3001:3001"
    # HOST_CLIENT_PORT="3002:3002"

    # Optional: Database credentials (defaults work fine)
    # CLICKHOUSE_PASSWORD=frog
    # POSTGRES_USER=frog
    # POSTGRES_PASSWORD=frog
    # POSTGRES_DB=analytics
    # CLICKHOUSE_DB=analytics
    ```

    <Callout type="info">
      To generate a secure `BETTER_AUTH_SECRET`, you can use:

      ```bash
      openssl rand -hex 32
      ```
    </Callout>
  </Step>

  <Step>
    ### Choose Your Setup Method [#choose-your-setup-method]

    <Tabs items="['Built-in Caddy (Automatic SSL)', 'Without Caddy']">
      <Tab value="Built-in Caddy (Automatic SSL)">
        If you don't have a reverse proxy and want automatic SSL certificates, use the default docker-compose.yml:

        ```bash
        docker compose up -d
        ```

        This will:

        * Start all services including Caddy
        * Automatically obtain SSL certificates
        * Make your app available at `https://your.domain.com`
      </Tab>

      <Tab value="Without Caddy">
        If you have your own reverse proxy (Nginx, Traefik, Coolify, etc.), you need to exclude Caddy and expose the ports:

        1. **Option B1: Modify the .env file**

           ```bash
           # Add these lines to expose ports
           HOST_BACKEND_PORT="3001:3001"
           HOST_CLIENT_PORT="3002:3002"
           ```

           Then start without Caddy:

           ```bash
           docker compose up -d backend client clickhouse postgres
           ```

        2. **Option B2: Use docker-compose.override.yml**
           Create a `docker-compose.override.yml` file:

           ```yaml
           services:
             backend:
               ports:
                 - "3001:3001"
             client:
               ports:
                 - "3002:3002"
           ```

           Then start without Caddy:

           ```bash
           docker compose up -d backend client clickhouse postgres
           ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure Your Reverse Proxy [#configure-your-reverse-proxy]

    If you're using your own reverse proxy, configure it to:

    * Proxy requests to `/api/*` to `http://localhost:3001`
    * Proxy all other requests to `http://localhost:3002`

    Example configurations:

    <Tabs items="['Nginx', 'Traefik']">
      <Tab value="Nginx">
        ```nginx
        server {
            listen 80;
            server_name your.domain.com;
            return 301 https://$host$request_uri;
        }

        server {
            listen 443 ssl;
            server_name your.domain.com;

            # Your SSL configuration here

            location /api/ {
                proxy_pass http://localhost:3001;
                proxy_set_header Host $host;
                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;
            }

            location / {
                proxy_pass http://localhost:3002;
                proxy_set_header Host $host;
                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;
            }
        }
        ```
      </Tab>

      <Tab value="Traefik">
        ```yml
        services:
          backend:
            labels:
              - "traefik.enable=true"
              - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && PathPrefix(`/api`)"
              - "traefik.http.routers.rybbit-api.tls.certresolver=letsencrypt"
              - "traefik.http.services.rybbit-api.loadbalancer.server.port=3001"
          
          client:
            labels:
              - "traefik.enable=true"
              - "traefik.http.routers.rybbit-client.rule=Host(`your.domain.com`)"
              - "traefik.http.routers.rybbit-client.tls.certresolver=letsencrypt"
              - "traefik.http.services.rybbit-client.loadbalancer.server.port=3002"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Start the Services [#start-the-services]

    ```bash
    # Start all services
    docker compose up -d

    # Or start specific services (without Caddy)
    docker compose up -d backend client clickhouse postgres
    ```
  </Step>

  <Step>
    ### Verify Setup [#verify-setup]

    Check that all services are running:

    ```bash
    docker compose ps
    ```

    Monitor logs:

    ```bash
    docker compose logs -f
    ```
  </Step>

  <Step>
    ### Create Admin Account [#create-admin-account]

    Navigate to `https://your.domain.com/signup` and create your admin account.
  </Step>
</Steps>

## Service Architecture [#service-architecture]

Rybbit consists of these services:

* **client**: Next.js frontend (port 3002)
* **backend**: Node.js API server (port 3001)
* **postgres**: User data and configuration
* **clickhouse**: Analytics data storage
* **redis**: Session tracking and background job queues
* **caddy**: Reverse proxy with automatic SSL (optional)

## Common Configurations [#common-configurations]

### Using Custom Ports [#using-custom-ports]

If you need different host ports (e.g., if 3001/3002 are already in use):

```bash
HOST_BACKEND_PORT="8080:3001"
HOST_CLIENT_PORT="8081:3002"
```

### Using with Coolify [#using-with-coolify]

Since Coolify uses Traefik instead of Caddy as proxy, some modifications have to be made in a `docker-compose.yaml` file to avoid conflicts. Specifically, you need to:

* remove Caddy service and volumes
* add network labels to all services
* remove `build` and `ports` properties from backend and client services

Here's a modified version of docker-compose that works on Coolify:

```yaml
services:
  clickhouse:
    container_name: clickhouse
    image: clickhouse/clickhouse-server:26.3.17.4
    volumes:
      - clickhouse-data:/var/lib/clickhouse
    configs:
      - source: clickhouse_network
        target: /etc/clickhouse-server/config.d/network.xml
      - source: clickhouse_logging
        target: /etc/clickhouse-server/config.d/logging_rules.xml
      # Profile (user-level) settings are only read from users.d, not config.d
      - source: clickhouse_user_settings
        target: /etc/clickhouse-server/users.d/user_settings.xml
    environment:
      - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
      - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
      - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://localhost:8123/ping",
        ]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    labels:
      - traefik.enable=false

  postgres:
    image: postgres:17.4
    container_name: postgres
    environment:
      - POSTGRES_USER=${POSTGRES_USER:-frog}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
      - POSTGRES_DB=${POSTGRES_DB:-analytics}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    labels:
      - traefik.enable=false

  redis:
    image: redis:8.6.4-alpine
    container_name: redis
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 5s
    restart: unless-stopped
    command:
      - redis-server
      - --requirepass
      - ${REDIS_PASSWORD:-changeme}
      - --appendonly
      - "yes"
      - --appendfsync
      - everysec
      - --maxmemory-policy
      - noeviction
    labels:
      - traefik.enable=false

  backend:
    image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}
    container_name: backend
    environment:
      - NODE_ENV=production
      - CLICKHOUSE_HOST=http://clickhouse:8123
      - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
      - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_DB=${POSTGRES_DB:-analytics}
      - POSTGRES_USER=${POSTGRES_USER:-frog}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
      - BASE_URL=${BASE_URL}
      - DOMAIN_NAME=${DOMAIN_NAME}
      - DISABLE_SIGNUP=${DISABLE_SIGNUP}
      - DISABLE_TELEMETRY=${DISABLE_TELEMETRY}
      - MAPBOX_TOKEN=${MAPBOX_TOKEN}
    depends_on:
      clickhouse:
        condition: service_healthy
      postgres:
        condition: service_started
      redis:
        condition: service_healthy
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://127.0.0.1:3001/api/health",
        ]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    labels:
      - traefik.enable=true
      - traefik.docker.network=coolify
      - traefik.http.routers.rybbit-backend.entrypoints=https
      - traefik.http.routers.rybbit-backend.tls=true
      - traefik.http.routers.rybbit-backend.rule=Host(`${DOMAIN_NAME}`) && (Path(`/api`) || PathPrefix(`/api/`))
      - traefik.http.services.rybbit-backend.loadbalancer.server.port=3001
      - traefik.http.routers.rybbit-backend.priority=100
      - traefik.http.middlewares.rybbit-forward-headers.headers.customrequestheaders.X-Forwarded-Proto=https
      - traefik.http.middlewares.rybbit-forward-headers.headers.customrequestheaders.X-Forwarded-Host=${DOMAIN_NAME}
      - traefik.http.routers.rybbit-backend.middlewares=rybbit-forward-headers

  client:
    image: ghcr.io/rybbit-io/rybbit-client:${IMAGE_TAG:-latest}
    container_name: client
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_BACKEND_URL=${BASE_URL}
      - NEXT_PUBLIC_DISABLE_SIGNUP=${DISABLE_SIGNUP}
      - DOMAIN_NAME=${DOMAIN_NAME}
    depends_on:
      - backend
    restart: unless-stopped
    labels:
      - traefik.enable=true
      - traefik.docker.network=coolify
      - traefik.http.routers.rybbit-client.entrypoints=https
      - traefik.http.routers.rybbit-client.tls=true
      - traefik.http.routers.rybbit-client.rule=Host(`${DOMAIN_NAME}`)
      - traefik.http.services.rybbit-client.loadbalancer.server.port=3002
      - traefik.http.routers.rybbit-client.priority=10

volumes:
  clickhouse-data:
  postgres-data:
  redis-data:

configs:
  clickhouse_network:
    content: |
      <clickhouse>
          <listen_host>0.0.0.0</listen_host>
      </clickhouse>

  clickhouse_logging:
    content: |
      <clickhouse>
        <logger>
            <level>warning</level>
            <console>true</console>
        </logger>
        <query_thread_log remove="remove"/>
        <query_log remove="remove"/>
        <text_log remove="remove"/>
        <trace_log remove="remove"/>
        <metric_log remove="remove"/>
        <asynchronous_metric_log remove="remove"/>
        <session_log remove="remove"/>
        <part_log remove="remove"/>
        <latency_log remove="remove"/>
        <processors_profile_log remove="remove"/>
      </clickhouse>

  clickhouse_user_settings:
    content: |
      <clickhouse>
        <profiles>
          <default>
            <enable_json_type>1</enable_json_type>
            <!-- 26.3+ enables async_insert by default; the backend already
                 batches app-side, so keep inserts synchronous -->
            <async_insert>0</async_insert>
            <log_queries>0</log_queries>
            <log_query_threads>0</log_query_threads>
            <log_processors_profiles>0</log_processors_profiles>
          </default>
        </profiles>
      </clickhouse>
```

To deploy Rybbit on Coolify, you need to:

1. Create a new project and resource using `docker-compose.yaml` file provided above
2. Make sure "Escape special characters in labels" option is unchecked when adding docker-compose file so that env variables in labels are read properly
3. Set the environment variables in Coolify's interface
4. Add a domain for `client` service in Coolify's interface
5. Deploy all services

Note: you don't need to add a domain for `backend` service in Coolify since client and backend services share the same domain.

### Using with Nginx Proxy Manager [#using-with-nginx-proxy-manager]

1. Set up port exposure in your .env:
   ```bash
   HOST_BACKEND_PORT="3001:3001"
   HOST_CLIENT_PORT="3002:3002"
   ```

2. Create a proxy host pointing to your server IP:3002

3. Add a custom location `/api/*` pointing to your server IP:3001

### Database Persistence [#database-persistence]

Data is automatically persisted in Docker volumes:

* `rybbit_clickhouse-data`: Analytics data
* `rybbit_postgres-data`: User accounts and site configurations

## Advanced Configurations [#advanced-configurations]

For specific reverse proxy setups, see our detailed guides:

* **[Custom Nginx Setup](/docs/self-hosting-guides/custom-nginx)** - Complete Nginx configuration with SSL
* **[Nginx Proxy Manager](/docs/self-hosting-guides/nginx-proxy-manager)** - NPM setup without port exposure

These guides provide step-by-step instructions for integrating Rybbit with your existing infrastructure.

## Troubleshooting [#troubleshooting]

### Services won't start [#services-wont-start]

```bash
# Check logs
docker compose logs

# Check service status
docker compose ps
```

### Port conflicts [#port-conflicts]

If you get port binding errors, either:

1. Change the host ports in your .env file
2. Stop the conflicting service
3. Use docker-compose.override.yml to customize ports

### Database connection issues [#database-connection-issues]

Ensure the database services are healthy:

```bash
docker compose ps
```

Both postgres and clickhouse should show "healthy" status.

<Callout type="info">
  For more advanced configurations and setup script options, see our [Advanced Self-Hosting Guide](/docs/self-hosting-guides/self-hosting-advanced).
</Callout>


# Create Annotation (/docs/api/annotations/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/annotations
    ```

    Creates an annotation. Any member with access to the site can create site annotations; organization-wide annotations (`scope: "organization"`) require an admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  title: { description: 'Short title (max 120 characters)', type: 'string', required: true },
  date: { description: 'ISO 8601 timestamp with Z or offset, or YYYY-MM-DD (read as midnight UTC)', type: 'string', required: true },
  endDate: { description: 'End of a range; must be after date', type: 'string', required: false },
  description: { description: 'Longer note (max 2000 characters)', type: 'string', required: false },
  color: { description: 'Marker color', type: 'string', typeDescription: '&#x22;amber&#x22; | &#x22;rose&#x22; | &#x22;sky&#x22; | &#x22;violet&#x22; | &#x22;lime&#x22;', required: false },
  icon: { description: 'A single emoji (or character) shown in the marker', type: 'string', required: false },
  isPublic: { description: 'Show on public dashboards and private links', type: 'boolean', default: 'false', required: false },
  scope: { description: 'Attach to this site or to every site in the organization', type: 'string', typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;', default: '&#x22;site&#x22;', required: false },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: { description: 'Always true', type: 'boolean' },
  annotationId: { description: 'ID of the new annotation', type: 'number' },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl -X POST "https://app.rybbit.io/api/sites/123/annotations" \
          -H "Authorization: Bearer YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "title": "Deployed v2.3.0",
            "date": "2026-08-24T14:10:00Z",
            "color": "sky",
            "scope": "organization"
          }'
        ```
      </Tab>

      <Tab value="Response">
        ```json
        { "success": true, "annotationId": 43 }
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Delete Annotation (/docs/api/annotations/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/annotations/:annotationId
    ```

    Deletes an annotation. Admins and owners can delete any annotation on their sites; members can delete only the annotations they created.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: { description: 'Site ID or site identifier', type: 'string | number', required: true },
  annotationId: { description: 'Annotation ID', type: 'number', required: true },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE "https://app.rybbit.io/api/sites/123/annotations/43" \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab value="Response">
        ```json
        { "success": true }
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Get Annotations (/docs/api/annotations/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/annotations
    ```

    Returns the annotations pinned to the site's traffic chart, ordered by date. Organization-wide annotations (those with a `null` `siteId`) are included for every site in the organization.

    Anonymous viewers of a public dashboard or a private link only receive annotations with `isPublic: true`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  start_date: {
    description: 'Only annotations that end on or after the start of this day (YYYY-MM-DD). May be sent without end_date.',
    type: 'string',
    required: false,
  },
  end_date: {
    description: 'Only annotations that start before the end of this day (YYYY-MM-DD). May be sent without start_date; must not precede start_date.',
    type: 'string',
    required: false,
  },
  time_zone: {
    description: 'IANA timezone the day bounds are read in',
    type: 'string',
    default: 'UTC',
    required: false,
  },
}"
    />

    ### Response [#response]

    An array of annotation objects.

    <TypeTable
      type="{
  annotationId: { description: 'Unique annotation ID', type: 'number' },
  siteId: { description: 'Site the annotation belongs to, or null for organization-wide annotations', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator user ID', type: 'string | null' },
  userName: { description: 'Creator display name', type: 'string | null' },
  title: { description: 'Short title shown on the chart', type: 'string' },
  description: { description: 'Longer note', type: 'string | null' },
  date: { description: 'ISO 8601 timestamp the annotation is pinned to', type: 'string' },
  endDate: { description: 'ISO 8601 end timestamp for range annotations', type: 'string | null' },
  color: { description: 'Marker color', type: 'string | null', typeDescription: '&#x22;amber&#x22; | &#x22;rose&#x22; | &#x22;sky&#x22; | &#x22;violet&#x22; | &#x22;lime&#x22; | null' },
  icon: { description: 'Single emoji shown in the marker', type: 'string | null' },
  isPublic: { description: 'Whether public dashboards and private links show it', type: 'boolean' },
  createdAt: { description: 'Creation timestamp', type: 'string' },
  updatedAt: { description: 'Last update timestamp', type: 'string' },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl "https://app.rybbit.io/api/sites/123/annotations?start_date=2026-08-01&end_date=2026-08-31" \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab value="Response">
        ```json
        [
          {
            "annotationId": 42,
            "siteId": 123,
            "organizationId": "org_abc",
            "userId": "user_xyz",
            "userName": "Bill",
            "title": "Product Hunt launch",
            "description": "Finished #2 Product of the Day.",
            "date": "2026-08-18T07:00:00.000Z",
            "endDate": null,
            "color": "amber",
            "icon": "🚀",
            "isPublic": true,
            "createdAt": "2026-08-18 07:05:12.1",
            "updatedAt": "2026-08-18 07:05:12.1"
          }
        ]
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Update Annotation (/docs/api/annotations/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:site/annotations/:annotationId
    ```

    Partial update: only the fields you send change. Admins and owners can edit any annotation on their sites; members can edit only the annotations they created. Changing `scope` requires an admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: { description: 'Site ID or site identifier', type: 'string | number', required: true },
  annotationId: { description: 'Annotation ID', type: 'number', required: true },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  title: { description: 'Short title (max 120 characters)', type: 'string', required: false },
  date: { description: 'ISO 8601 timestamp with Z or offset, or YYYY-MM-DD', type: 'string', required: false },
  endDate: { description: 'End of a range, or null to turn a range back into a point', type: 'string | null', required: false },
  description: { description: 'Longer note, or null to clear', type: 'string | null', required: false },
  color: { description: 'Marker color, or null for the neutral default', type: 'string | null', required: false },
  icon: { description: 'A single emoji (or character), or null to clear', type: 'string | null', required: false },
  isPublic: { description: 'Show on public dashboards and private links', type: 'boolean', required: false },
  scope: { description: 'Move between site and organization-wide', type: 'string', typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;', required: false },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl -X PUT "https://app.rybbit.io/api/sites/123/annotations/43" \
          -H "Authorization: Bearer YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{ "title": "Deployed v2.3.0 (rolled back)", "color": "rose" }'
        ```
      </Tab>

      <Tab value="Response">
        ```json
        { "success": true }
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Create Organization API Key (/docs/api/api-keys/create-org)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/api-keys
    ```

    Creates an API key **owned by the organization itself**, rather than by your user account. The key authenticates as the organization (org-admin authority over its sites), so it survives member departures, and its plan gating, [rate limits](/docs/api/getting-started#rate-limits-cloud-only), and key-count limit all follow the owning organization's subscription. Organization keys are issued with the `rb_org_` prefix.

    <Callout type="warn">
      You must be an 

      **owner or admin**

       of the target organization. This endpoint accepts your dashboard 

      **session**

       or an 

      **unrestricted (full-access) user API key**

       — scoped keys and organization keys are rejected, so an organization key cannot mint other keys.
    </Callout>

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'The ID of the organization that will own the key',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'A label for the key',
    type: 'string',
    required: true,
  },
  expiresIn: {
    description: 'Seconds until the key expires. Omit for a key that never expires.',
    type: 'number',
    required: false,
  },
  permissions: {
    description: 'Scope the key to specific `resource: action[]` pairs (e.g. `{ &#x22;analytics&#x22;: [&#x22;read&#x22;], &#x22;goals&#x22;: [&#x22;read&#x22;, &#x22;write&#x22;] }`). Omit entirely for a full-access key.',
    type: 'object',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created API key object. The full `key` value carries the `rb_org_` prefix.

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  key: {
    description: 'The secret key value (prefixed with `rb_org_`)',
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string',
  },
  start: {
    description: 'A non-secret prefix of the key for display',
    type: 'string',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string',
  },
  referenceId: {
    description: 'The ID of the organization that owns the key',
    type: 'string',
  },
  userId: {
    description: 'The ID of the admin/owner who created the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if the key never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
}"
    />

    **Note:** Additional fields may be present in the response object.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_123/api-keys" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"name": "CI pipeline", "expiresIn": 2592000}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations/org_123/api-keys',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'CI pipeline',
              expiresIn: 2592000
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/organizations/org_123/api-keys',
            json={
                'name': 'CI pipeline',
                'expiresIn': 2592000
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/org_123/api-keys");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'name' => 'CI pipeline',
            'expiresIn' => 2592000
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/organizations/org_123/api-keys")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          name: 'CI pipeline',
          expiresIn: 2592000
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "name": "CI pipeline",
          "expiresIn": 2592000
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/org_123/api-keys", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/organizations/org_123/api-keys")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "name": "CI pipeline",
                "expiresIn": 2592000
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/org_123/api-keys"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/organizations/org_123/api-keys", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    <Callout type="warn">
      The full 

      `key`

       value is returned 

      **only once**

      , at creation. Store it securely — it cannot be retrieved again.
    </Callout>

    ```json title="Response"
    {
      "id": "key_8f3a1b2c4d5e6f7g",
      "key": "rb_org_xxxxxxxxxxxxxxxxxxxx",
      "name": "CI pipeline",
      "start": "rb_org_xxxx",
      "prefix": "rb_org_",
      "referenceId": "org_123",
      "userId": "user_2a9b8c7d6e5f4g3h",
      "enabled": true,
      "expiresAt": "2026-07-25T12:00:00.000Z",
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-25T12:00:00.000Z",
      "rateLimitEnabled": false,
      "rateLimitMax": 10,
      "rateLimitTimeWindow": 86400000
    }
    ```

    <Callout>
      On Rybbit Cloud, organization API keys require the organization to be on a Standard or Pro plan; free/basic plans receive HTTP 403. Each organization also has a plan-based key-count limit — creating a key past the limit returns HTTP 403.
    </Callout>
  </div>
</div>


# Create API Key (/docs/api/api-keys/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/user/api-keys
    ```

    Creates a new API key scoped to your user account (and its organizations). To create a key owned by an organization instead, see [Create Organization API Key](/docs/api/api-keys/create-org).

    <Callout type="warn">
      This endpoint accepts your logged-in dashboard 

      **session**

       or an 

      **unrestricted (full-access) user API key**

      . Scoped keys and organization keys are rejected — so a scoped key cannot mint new keys, but a session or full-access key can. Send your session cookie or 

      `Authorization: Bearer`

       header with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'A label for the key',
    type: 'string',
    required: true,
  },
  expiresIn: {
    description: 'Seconds until the key expires. Omit for a key that never expires.',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created API key object.

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  key: {
    description: 'The secret key value',
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string',
  },
  start: {
    description: 'A non-secret prefix of the key for display',
    type: 'string',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string',
  },
  userId: {
    description: 'The ID of the user that owns the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if the key never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
}"
    />

    **Note:** Additional fields may be present in the response object.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/user/api-keys" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"name": "CI pipeline", "expiresIn": 2592000}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/user/api-keys',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'CI pipeline',
              expiresIn: 2592000
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/user/api-keys',
            json={
                'name': 'CI pipeline',
                'expiresIn': 2592000
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/user/api-keys");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'name' => 'CI pipeline',
            'expiresIn' => 2592000
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/user/api-keys")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          name: 'CI pipeline',
          expiresIn: 2592000
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "name": "CI pipeline",
          "expiresIn": 2592000
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/user/api-keys", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/user/api-keys")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "name": "CI pipeline",
                "expiresIn": 2592000
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/user/api-keys"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/user/api-keys", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    <Callout type="warn">
      The full 

      `key`

       value is returned 

      **only once**

      , at creation. Store it securely — it cannot be retrieved again.
    </Callout>

    ```json title="Response"
    {
      "id": "key_8f3a1b2c4d5e6f7g",
      "key": "rybbit_sk_live_xxxxxxxxxxxxxxxxxxxx",
      "name": "CI pipeline",
      "start": "rybbit_sk_live_xxxx",
      "prefix": "rybbit_sk_live_",
      "userId": "user_2a9b8c7d6e5f4g3h",
      "enabled": true,
      "expiresAt": "2026-07-25T12:00:00.000Z",
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-25T12:00:00.000Z",
      "rateLimitEnabled": false,
      "rateLimitMax": 10,
      "rateLimitTimeWindow": 86400000
    }
    ```

    <Callout>
      On Rybbit Cloud, API keys require a Standard or Pro plan; free/basic plans receive HTTP 403. 

      [Rate limits](/docs/api/getting-started#rate-limits-cloud-only)

       are charged to 

      **you**

      , the owning user, and are shared by every personal key you hold across every organization you belong to — creating a key does not add budget, and a plan change applies to keys you already have. For a budget that belongs to the organization instead, create an 

      [organization key](/docs/api/api-keys/create-org)

      .
    </Callout>
  </div>
</div>


# Delete API Key (/docs/api/api-keys/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/api-key/delete
    ```

    Revokes (deletes) an existing API key. The key is identified by its `keyId`.

    <Callout type="warn">
      This endpoint uses 

      **POST**

      , not HTTP DELETE. Revoking a key is immediate and permanent — any client still using it will start receiving 401 responses.
    </Callout>

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  keyId: {
    description: 'The id of the API key to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns a success flag.

    <TypeTable
      type="{
  success: {
    description: 'Indicates the API key was successfully deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/api-key/delete" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"keyId": "key_8f3a1b2c4d5e6f7g"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/api-key/delete',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              keyId: 'key_8f3a1b2c4d5e6f7g'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/api-key/delete',
            json={
                'keyId': 'key_8f3a1b2c4d5e6f7g'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/api-key/delete");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'keyId' => 'key_8f3a1b2c4d5e6f7g'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/api-key/delete")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          keyId: 'key_8f3a1b2c4d5e6f7g'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "keyId": "key_8f3a1b2c4d5e6f7g"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/api-key/delete", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/api-key/delete")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "keyId": "key_8f3a1b2c4d5e6f7g"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/api-key/delete"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/api-key/delete", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# List API Keys (/docs/api/api-keys/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/auth/api-key/list
    ```

    Returns all API keys owned by the authenticated user, or by a specific organization.

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID. If provided, returns organization-owned keys instead of your user-owned keys.',
    type: 'string',
    required: false,
  },
  limit: {
    description: 'Maximum number of keys to return.',
    type: 'number',
    required: false,
  },
  offset: {
    description: 'Number of keys to skip.',
    type: 'number',
    required: false,
  },
  sortBy: {
    description: 'Field to sort by (e.g. createdAt, name, expiresAt).',
    type: 'string',
    required: false,
  },
  sortDirection: {
    description: 'Sort direction.',
    type: &#x22;'asc' | 'desc'&#x22;,
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  apiKeys: {
    description: 'Array of API key objects.',
    type: 'ApiKey[]',
  },
  total: {
    description: 'Total number of matching keys.',
    type: 'number',
  },
  limit: {
    description: 'The limit that was applied.',
    type: 'number | null',
  },
  offset: {
    description: 'The offset that was applied.',
    type: 'number | null',
  },
}"
    />

    #### ApiKey Object [#apikey-object]

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string | null',
  },
  start: {
    description: 'Non-secret leading characters of the key, for display',
    type: 'string | null',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string | null',
  },
  userId: {
    description: 'ID of the user that owns the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if it never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
  requestCount: {
    description: 'Requests made in the current rate-limit window',
    type: 'number',
  },
  remaining: {
    description: 'Remaining requests, or null if not limited by count',
    type: 'number | null',
  },
  lastRequest: {
    description: 'Timestamp of the most recent request',
    type: 'string | null',
  },
  metadata: {
    description: 'Extra metadata stored on the key',
    type: 'object | null',
  },
  permissions: {
    description: 'Permissions associated with the key',
    type: 'object | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/auth/api-key/list?limit=20" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/api-key/list?limit=20',
          {
            method: 'GET',
            credentials: 'include'
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/auth/api-key/list?limit=20',
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/api-key/list?limit=20");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/api-key/list?limit=20")
        req = Net::HTTP::Get.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/auth/api-key/list?limit=20", nil)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/auth/api-key/list?limit=20")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/api-key/list?limit=20"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var response = await client.GetAsync("https://app.rybbit.io/api/auth/api-key/list?limit=20");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    <Callout>
      The secret key value is only returned once, at creation. This endpoint returns the non-secret 

      `start`

      /

      `prefix`

       for display, never the full key.
    </Callout>

    ```json title="Response"
    {
      "apiKeys": [
        {
          "id": "key_8f3a1b2c4d5e6f7g",
          "name": "CI pipeline",
          "start": "rybbit_sk_live_xxxx",
          "prefix": "rybbit_sk_live_",
          "userId": "user_2a9b8c7d6e5f4g3h",
          "enabled": true,
          "expiresAt": "2026-07-25T12:00:00.000Z",
          "createdAt": "2026-06-25T12:00:00.000Z",
          "updatedAt": "2026-06-25T12:00:00.000Z",
          "rateLimitEnabled": false,
          "rateLimitMax": 10,
          "rateLimitTimeWindow": 86400000,
          "requestCount": 42,
          "remaining": null,
          "lastRequest": "2026-06-25T13:30:00.000Z",
          "metadata": null,
          "permissions": null
        }
      ],
      "total": 1,
      "limit": 20,
      "offset": 0
    }
    ```
  </div>
</div>


# Update API Key (/docs/api/api-keys/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/api-key/update
    ```

    <Callout>
      This endpoint uses 

      **POST**

      , not PUT or PATCH.
    </Callout>

    Updates mutable fields on an existing API key. The key is identified by its `keyId`.

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  keyId: {
    description: 'The id of the API key to update',
    type: 'string',
    required: true,
  },
  name: {
    description: 'A new label for the key',
    type: 'string',
    required: false,
  },
  enabled: {
    description: 'Enable or disable the key',
    type: 'boolean',
    required: false,
  },
  expiresIn: {
    description: 'New expiry in seconds from now. Pass null to make the key never expire.',
    type: 'number | null',
    required: false,
  },
  rateLimitEnabled: {
    description: 'Legacy per-key rate limit toggle. Has no effect — [rate limits](/docs/api/getting-started#rate-limits-cloud-only) are enforced per credential owner and follow that owner\'s plan',
    type: 'boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the updated API key object (without the secret key value).

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string | null',
  },
  start: {
    description: 'Non-secret leading characters of the key, for display',
    type: 'string | null',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string | null',
  },
  userId: {
    description: 'ID of the user that owns the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if it never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
}"
    />

    **Note:** Additional fields may be present in the response object.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/api-key/update" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"keyId": "key_8f3a1b2c4d5e6f7g", "name": "CI pipeline (rotated)", "enabled": true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/api-key/update',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              keyId: 'key_8f3a1b2c4d5e6f7g',
              name: 'CI pipeline (rotated)',
              enabled: true
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/api-key/update',
            json={
                'keyId': 'key_8f3a1b2c4d5e6f7g',
                'name': 'CI pipeline (rotated)',
                'enabled': True
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/api-key/update");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'keyId' => 'key_8f3a1b2c4d5e6f7g',
            'name' => 'CI pipeline (rotated)',
            'enabled' => true
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/api-key/update")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          keyId: 'key_8f3a1b2c4d5e6f7g',
          name: 'CI pipeline (rotated)',
          enabled: true
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "keyId": "key_8f3a1b2c4d5e6f7g",
          "name": "CI pipeline (rotated)",
          "enabled": true
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/api-key/update", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/api-key/update")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "keyId": "key_8f3a1b2c4d5e6f7g",
                "name": "CI pipeline (rotated)",
                "enabled": true
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\", \"name\": \"CI pipeline (rotated)\", \"enabled\": true}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/api-key/update"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\", \"name\": \"CI pipeline (rotated)\", \"enabled\": true}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/api-key/update", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "key_8f3a1b2c4d5e6f7g",
      "name": "CI pipeline (rotated)",
      "start": "rybbit_sk_live_xxxx",
      "prefix": "rybbit_sk_live_",
      "userId": "user_2a9b8c7d6e5f4g3h",
      "enabled": true,
      "expiresAt": "2026-07-25T12:00:00.000Z",
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-26T12:00:00.000Z",
      "rateLimitEnabled": false,
      "rateLimitMax": 10,
      "rateLimitTimeWindow": 86400000
    }
    ```
  </div>
</div>


# Get AI Summary (/docs/api/bots/ai-summary)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/ai-summary
    ```

    Returns one row per AI operator: how much of your site it read, and how many visits it sent back.

    The two numbers come from different places. Reads are bot events whose user agent names the operator; visits back are sessions in your normal analytics that arrived from that company's product (the `AI` acquisition channel). Neither is very interesting alone — "OpenAI read 4,120 pages and sent 12 visits" is the sentence this endpoint exists to produce.

    Operators that only read, and operators that only referred, both appear; the missing side reads `0`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Filters apply to both halves, using the bot filter subset described in [Get Bots by Dimension](/docs/api/bots/by-dimension).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of operator rows, ordered by reads descending',
    type: 'AiSummaryRow[]',
  },
}"
    />

    #### AiSummaryRow Object [#aisummaryrow-object]

    <TypeTable
      type="{
  operator: {
    description: 'Who runs the bot, e.g. &#x22;OpenAI&#x22;',
    type: 'string',
  },
  crawls: {
    description: 'Total AI requests from this operator',
    type: 'number',
  },
  training_crawls: {
    description: 'Requests with purpose ai_training',
    type: 'number',
  },
  search_crawls: {
    description: 'Requests with purpose ai_search',
    type: 'number',
  },
  agent_requests: {
    description: 'Requests with purpose ai_agent',
    type: 'number',
  },
  referrals: {
    description: 'Sessions that arrived from this operator\'s product',
    type: 'number',
  },
  crawls_per_referral: {
    description: 'Reads per visit sent back. 0 when the operator sent nobody back — there is no rate to report.',
    type: 'number',
  },
}"
    />

    <Callout>
      Only bots that execute JavaScript reach Rybbit. Crawlers that fetch HTML and run nothing — which includes most training crawlers — are absent unless your server reports them. See [Bot detection](/docs/bot-detection#reporting-crawlers-that-never-run-javascript).
    </Callout>
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/ai-summary?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/ai-summary?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/ai-summary',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York',
            },
            headers={'Authorization': 'Bearer your_api_key_here'},
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "operator": "OpenAI",
          "crawls": 6120,
          "training_crawls": 4400,
          "search_crawls": 900,
          "agent_requests": 820,
          "referrals": 214,
          "crawls_per_referral": 28.6
        },
        {
          "operator": "Perplexity",
          "crawls": 1904,
          "training_crawls": 0,
          "search_crawls": 1300,
          "agent_requests": 604,
          "referrals": 341,
          "crawls_per_referral": 5.6
        }
      ]
    }
    ```
  </div>
</div>


# Get Bots by Dimension (/docs/api/bots/by-dimension)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/by-dimension
    ```

    Returns bot requests broken down by a dimension.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Bot filtering supports a subset of filter parameters: `browser`, `browser_version`, `operating_system`, `operating_system_version`, `country`, `region`, `city`, `device_type`, `referrer`, `hostname`, `pathname`, `querystring`, `dimensions`, `user_id`, `lat`, and `lon`.

    <TypeTable
      type="{
  dimension: {
    description: 'The dimension to group by',
    type: 'string',
    typeDescription: '&#x22;browser&#x22; | &#x22;browser_version&#x22; | &#x22;operating_system&#x22; | &#x22;operating_system_version&#x22; | &#x22;country&#x22; | &#x22;region&#x22; | &#x22;city&#x22; | &#x22;device_type&#x22; | &#x22;referrer&#x22; | &#x22;hostname&#x22; | &#x22;pathname&#x22; | &#x22;dimensions&#x22; | &#x22;asn_org&#x22; | &#x22;asn_provider&#x22; | &#x22;bot_category&#x22; | &#x22;bot_name&#x22; | &#x22;bot_operator&#x22; | &#x22;bot_purpose&#x22; | &#x22;matched_ua_pattern&#x22;',
    required: true,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  purpose: {
    description: 'Restrict results to one bot purpose. &#x22;ai&#x22; covers all three AI purposes; &#x22;ai_crawler&#x22; covers training and answer-engine crawling but not agents.',
    type: 'string',
    typeDescription: '&#x22;ai&#x22; | &#x22;ai_crawler&#x22; | &#x22;ai_training&#x22; | &#x22;ai_search&#x22; | &#x22;ai_agent&#x22; | &#x22;search&#x22; | &#x22;social_preview&#x22; | &#x22;seo&#x22; | &#x22;monitoring&#x22; | &#x22;security&#x22; | &#x22;scripted&#x22; | &#x22;headless&#x22;',
    required: false,
  },
  layer: {
    description: 'Restrict results to a single detection layer',
    type: 'string',
    typeDescription: '&#x22;ua_pattern&#x22; | &#x22;header_heuristics&#x22; | &#x22;client_signals&#x22; | &#x22;bot_asn&#x22; | &#x22;rate_anomaly&#x22;',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Paginated response object',
    type: 'PaginatedResponse',
  },
}"
    />

    #### PaginatedResponse Object [#paginatedresponse-object]

    <TypeTable
      type="{
  data: {
    description: 'Array of dimension breakdown objects',
    type: 'BotDimension[]',
  },
  totalCount: {
    description: 'Total number of distinct dimension values',
    type: 'number',
  },
}"
    />

    #### BotDimension Object [#botdimension-object]

    <TypeTable
      type="{
  value: {
    description: 'The dimension value',
    type: 'string',
  },
  hostname: {
    description: 'Hostname (only populated when dimension is &#x22;pathname&#x22;, otherwise empty)',
    type: 'string',
  },
  count: {
    description: 'Number of bot requests for this value',
    type: 'number',
  },
  percentage: {
    description: 'Share of bot requests for this value',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/by-dimension',
            params={
                'dimension': 'browser',
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "data": [
          { "value": "Chrome", "hostname": "", "count": 980, "percentage": 53.26 },
          { "value": "HeadlessChrome", "hostname": "", "count": 540, "percentage": 29.35 }
        ],
        "totalCount": 12
      }
    }
    ```
  </div>
</div>


# Get Bot Overview (/docs/api/bots/overview)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/overview
    ```

    Returns aggregate bot-traffic metrics with a breakdown by detection layer.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Bot filtering supports a subset of filter parameters: `browser`, `browser_version`, `operating_system`, `operating_system_version`, `country`, `region`, `city`, `device_type`, `referrer`, `hostname`, `pathname`, `querystring`, `dimensions`, `user_id`, `lat`, and `lon`.

    <TypeTable
      type="{
  layer: {
    description: 'Restrict results to a single detection layer',
    type: 'string',
    typeDescription: '&#x22;ua_pattern&#x22; | &#x22;header_heuristics&#x22; | &#x22;client_signals&#x22; | &#x22;bot_asn&#x22; | &#x22;rate_anomaly&#x22;',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  bot_requests: {
    description: 'Total bot requests',
    type: 'number',
  },
  total_events: {
    description: 'Total requests (bots + humans)',
    type: 'number',
  },
  bot_percentage: {
    description: 'Bot requests as a percentage of all requests',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  ai_requests: {
    description: 'Requests from named AI systems: training crawlers, answer-engine indexers, and user-triggered agents',
    type: 'number',
  },
  ai_agent_requests: {
    description: 'Requests from user-triggered AI agents (a person asked an assistant to open the page)',
    type: 'number',
  },
  ai_crawler_requests: {
    description: 'Requests from AI training crawlers and answer-engine indexers',
    type: 'number',
  },
  ua_pattern: {
    description: 'Bot requests flagged by the user-agent pattern layer',
    type: 'number',
  },
  header_heuristics: {
    description: 'Bot requests flagged by the header-heuristics layer',
    type: 'number',
  },
  client_signals: {
    description: 'Bot requests flagged by the client-signals layer',
    type: 'number',
  },
  bot_asn: {
    description: 'Bot requests flagged by the known-bot-ASN layer',
    type: 'number',
  },
  rate_anomaly: {
    description: 'Bot requests flagged by the rate-anomaly layer',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/overview',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "bot_requests": 1840,
        "total_events": 48933,
        "bot_percentage": 3.76,
        "ai_requests": 940,
        "ai_agent_requests": 180,
        "ai_crawler_requests": 760,
        "ua_pattern": 1200,
        "header_heuristics": 410,
        "client_signals": 95,
        "bot_asn": 120,
        "rate_anomaly": 15
      }
    }
    ```
  </div>
</div>


# Get Bot Time Series (/docs/api/bots/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/time-series
    ```

    Returns bot request counts over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Bot filtering supports a subset of filter parameters: `browser`, `browser_version`, `operating_system`, `operating_system_version`, `country`, `region`, `city`, `device_type`, `referrer`, `hostname`, `pathname`, `querystring`, `dimensions`, `user_id`, `lat`, and `lon`.

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket granularity',
    type: 'string',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
  },
  purpose: {
    description: 'Restrict results to one bot purpose. &#x22;ai&#x22; covers all three AI purposes; &#x22;ai_crawler&#x22; covers training and answer-engine crawling but not agents.',
    type: 'string',
    typeDescription: '&#x22;ai&#x22; | &#x22;ai_crawler&#x22; | &#x22;ai_training&#x22; | &#x22;ai_search&#x22; | &#x22;ai_agent&#x22; | &#x22;search&#x22; | &#x22;social_preview&#x22; | &#x22;seo&#x22; | &#x22;monitoring&#x22; | &#x22;security&#x22; | &#x22;scripted&#x22; | &#x22;headless&#x22;',
    required: false,
  },
  layer: {
    description: 'Restrict results to a single detection layer',
    type: 'string',
    typeDescription: '&#x22;ua_pattern&#x22; | &#x22;header_heuristics&#x22; | &#x22;client_signals&#x22; | &#x22;bot_asn&#x22; | &#x22;rate_anomaly&#x22;',
    required: false,
  },
}"
    />

    #### Bucket Selection Guide [#bucket-selection-guide]

    | Bucket         | Best For                             |
    | -------------- | ------------------------------------ |
    | `minute`       | Real-time monitoring (last hour)     |
    | `five_minutes` | Short-term analysis (last few hours) |
    | `hour`         | Daily analysis                       |
    | `day`          | Weekly/monthly analysis              |
    | `week`         | Monthly/quarterly analysis           |
    | `month`        | Yearly analysis                      |

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
  },
  bot_requests: {
    description: 'Number of bot requests in this bucket',
    type: 'number',
  },
  ai_agent_requests: {
    description: 'Requests in this bucket from user-triggered AI agents',
    type: 'number',
  },
  ai_crawler_requests: {
    description: 'Requests in this bucket from AI training crawlers and answer-engine indexers',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/time-series',
            params={
                'bucket': 'hour',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        { "time": "2024-01-15 13:00:00", "bot_requests": 42 },
        { "time": "2024-01-15 14:00:00", "bot_requests": 58 }
      ]
    }
    ```
  </div>
</div>


# Get Error Events (/docs/api/errors/events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/errors/events
    ```

    Returns individual error occurrences for a specific error message, with full context including stack traces.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  errorMessage: {
    description: 'The error message to filter by',
    type: 'string',
    required: true,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    required: false,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 20,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of error event objects',
    type: 'ErrorEvent[]',
  },
}"
    />

    #### ErrorEvent Object [#errorevent-object]

    <TypeTable
      type="{
  timestamp: {
    description: 'When the error occurred',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  session_id: {
    description: 'Session identifier',
    type: 'string',
  },
  user_id: {
    description: 'User identifier',
    type: 'string | null',
  },
  pathname: {
    description: 'Page where error occurred',
    type: 'string',
  },
  hostname: {
    description: 'Hostname',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  message: {
    description: 'Error message',
    type: 'string',
  },
  stack: {
    description: 'Stack trace',
    type: 'string | null',
  },
  fileName: {
    description: 'Source file name',
    type: 'string | null',
  },
  lineNumber: {
    description: 'Line number in source',
    type: 'number | null',
  },
  columnNumber: {
    description: 'Column number in source',
    type: 'number | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          `https://app.rybbit.io/api/sites/1/errors/events?errorMessage=${encodeURIComponent("Cannot read property 'map' of undefined")}&limit=10`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/errors/events',
            params={
                'errorMessage': "Cannot read property 'map' of undefined",
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "timestamp": "2024-01-31T14:22:00.000Z",
          "session_id": "sess_abc123",
          "user_id": "user_xyz789",
          "pathname": "/dashboard",
          "hostname": "app.example.com",
          "browser": "Chrome",
          "browser_version": "120.0.0",
          "operating_system": "macOS",
          "device_type": "desktop",
          "country": "US",
          "message": "Cannot read property 'map' of undefined",
          "stack": "TypeError: Cannot read property 'map' of undefined\n    at Dashboard (dashboard.js:42:15)\n    at renderWithHooks (react-dom.js:1234:22)",
          "fileName": "dashboard.js",
          "lineNumber": 42,
          "columnNumber": 15
        }
      ]
    }
    ```
  </div>
</div>


# Get Error Names (/docs/api/errors/names)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/errors/names
    ```

    Returns a list of unique error messages with occurrence counts and affected session counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed). Enables paginated response format.',
    type: 'number',
    required: false,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 10,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of error objects (or paginated wrapper)',
    type: 'Error[] | PaginatedResponse',
  },
}"
    />

    #### Error Object [#error-object]

    <TypeTable
      type="{
  value: {
    description: 'Error message',
    type: 'string',
  },
  errorName: {
    description: 'Error type (TypeError, ReferenceError, etc.)',
    type: 'string',
  },
  count: {
    description: 'Total occurrences',
    type: 'number',
  },
  sessionCount: {
    description: 'Unique sessions affected',
    type: 'number',
  },
  percentage: {
    description: 'Percentage of total error sessions',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/errors/names',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "value": "Cannot read property 'map' of undefined",
          "errorName": "TypeError",
          "count": 156,
          "sessionCount": 89,
          "percentage": 34.5
        },
        {
          "value": "NetworkError when attempting to fetch resource",
          "errorName": "TypeError",
          "count": 98,
          "sessionCount": 72,
          "percentage": 27.9
        },
        {
          "value": "foo is not defined",
          "errorName": "ReferenceError",
          "count": 45,
          "sessionCount": 38,
          "percentage": 14.7
        }
      ]
    }
    ```
  </div>
</div>


# Get Error Time Series (/docs/api/errors/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/errors/time-series
    ```

    Returns error occurrence counts over time for a specific error message. Useful for tracking error trends and identifying when issues started.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  errorMessage: {
    description: 'The error message to filter by',
    type: 'string',
    required: true,
  },
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request succeeded',
    type: 'boolean',
  },
  data: {
    description: 'Array of time-bucketed counts',
    type: 'ErrorBucket[]',
  },
}"
    />

    #### ErrorBucket Object [#errorbucket-object]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  error_count: {
    description: 'Number of errors in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          `https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=${encodeURIComponent("Cannot read property 'map' of undefined")}&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/errors/time-series',
            params={
                'errorMessage': "Cannot read property 'map' of undefined",
                'bucket': 'hour',
                'start_date': '2024-01-30',
                'end_date': '2024-01-31',
                'time_zone': 'UTC'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": [
        {
          "time": "2024-01-30T00:00:00.000Z",
          "error_count": 5
        },
        {
          "time": "2024-01-30T01:00:00.000Z",
          "error_count": 3
        },
        {
          "time": "2024-01-30T02:00:00.000Z",
          "error_count": 8
        },
        {
          "time": "2024-01-30T03:00:00.000Z",
          "error_count": 2
        }
      ]
    }
    ```
  </div>
</div>


# Get Event Counts (/docs/api/events/count)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/count
    ```

    Returns time-bucketed event counts grouped by event type.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'day',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
  },
  pageview_count: {
    description: 'Number of pageviews in this bucket',
    type: 'number',
  },
  custom_event_count: {
    description: 'Number of custom events in this bucket',
    type: 'number',
  },
  performance_count: {
    description: 'Number of performance events in this bucket',
    type: 'number',
  },
  outbound_count: {
    description: 'Number of outbound link events in this bucket',
    type: 'number',
  },
  error_count: {
    description: 'Number of error events in this bucket',
    type: 'number',
  },
  button_click_count: {
    description: 'Number of button click events in this bucket',
    type: 'number',
  },
  copy_count: {
    description: 'Number of copy events in this bucket',
    type: 'number',
  },
  form_submit_count: {
    description: 'Number of form submit events in this bucket',
    type: 'number',
  },
  input_change_count: {
    description: 'Number of input change events in this bucket',
    type: 'number',
  },
  event_count: {
    description: 'Total events across all types in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/events/count',
            params={
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-15 00:00:00",
          "pageview_count": 4820,
          "custom_event_count": 312,
          "performance_count": 1200,
          "outbound_count": 88,
          "error_count": 14,
          "button_click_count": 540,
          "copy_count": 9,
          "form_submit_count": 33,
          "input_change_count": 120,
          "event_count": 7136
        }
      ]
    }
    ```
  </div>
</div>


# Get Events (/docs/api/events/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events
    ```

    Returns a paginated list of events (pageviews, custom events, and outbound clicks).

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page_size: {
    description: 'Number of results per page',
    type: 'number',
    default: 50,
  },
  since_timestamp: {
    description: 'Poll for new events after this timestamp (ISO 8601). Used for realtime polling. Returns up to 500 events.',
    type: 'string',
  },
  before_timestamp: {
    description: 'Fetch events before this timestamp (ISO 8601). Used for cursor-based pagination (scrolling back).',
    type: 'string',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of event objects',
    type: 'Event[]',
  },
  cursor: {
    description: 'Cursor metadata for pagination (only present when not using since_timestamp)',
    type: '{ hasMore: boolean, oldestTimestamp: string | null }',
  },
}"
    />

    #### Event Object [#event-object]

    <TypeTable
      type="{
  timestamp: {
    description: 'Event timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;copy&#x22; | &#x22;form_submit&#x22; | &#x22;input_change&#x22;',
  },
  event_name: {
    description: 'Custom event name',
    type: 'string',
  },
  properties: {
    description: 'Event properties as JSON string',
    type: 'string',
  },
  session_id: {
    description: 'Session identifier',
    type: 'string',
  },
  user_id: {
    description: 'User identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Identified user ID (if user has been identified)',
    type: 'string',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
  },
  querystring: {
    description: 'URL query string',
    type: 'string',
  },
  hostname: {
    description: 'Hostname',
    type: 'string',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  language: {
    description: 'Browser language',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  lat: {
    description: 'Latitude',
    type: 'number',
  },
  lon: {
    description: 'Longitude',
    type: 'number',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events',
            params={
                'page_size': 50,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "timestamp": "2024-01-31T14:22:00.000Z",
          "type": "custom_event",
          "event_name": "signup",
          "properties": "{\"plan\":\"pro\",\"source\":\"homepage\"}",
          "session_id": "abc123def456",
          "user_id": "user_abc123",
          "identified_user_id": "",
          "pathname": "/signup",
          "querystring": "",
          "hostname": "example.com",
          "page_title": "Sign Up",
          "referrer": "https://google.com",
          "browser": "Chrome",
          "browser_version": "120.0",
          "operating_system": "macOS",
          "operating_system_version": "14.0",
          "language": "en-US",
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "lat": 37.7749,
          "lon": -122.4194,
          "screen_width": 1920,
          "screen_height": 1080,
          "device_type": "desktop"
        },
        {
          "timestamp": "2024-01-31T14:21:00.000Z",
          "type": "pageview",
          "event_name": "",
          "properties": "{}",
          "session_id": "abc123def456",
          "user_id": "user_abc123",
          "identified_user_id": "",
          "pathname": "/pricing",
          "querystring": "",
          "hostname": "example.com",
          "page_title": "Pricing",
          "referrer": "https://example.com/",
          "browser": "Chrome",
          "browser_version": "120.0",
          "operating_system": "macOS",
          "operating_system_version": "14.0",
          "language": "en-US",
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "lat": 37.7749,
          "lon": -122.4194,
          "screen_width": 1920,
          "screen_height": 1080,
          "device_type": "desktop"
        }
      ],
      "cursor": {
        "hasMore": true,
        "oldestTimestamp": "2024-01-31T14:21:00.000Z"
      }
    }
    ```
  </div>
</div>


# Get Event Names (/docs/api/events/names)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/names
    ```

    Returns a list of unique custom event names with their occurrence counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of event name objects',
    type: 'EventName[]',
  },
}"
    />

    #### EventName Object [#eventname-object]

    <TypeTable
      type="{
  eventName: {
    description: 'Name of the custom event',
    type: 'string',
  },
  count: {
    description: 'Number of occurrences',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events/names',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "eventName": "signup",
          "count": 1250
        },
        {
          "eventName": "purchase",
          "count": 320
        },
        {
          "eventName": "add_to_cart",
          "count": 890
        },
        {
          "eventName": "newsletter_subscribe",
          "count": 456
        }
      ]
    }
    ```
  </div>
</div>


# Get Outbound Links (/docs/api/events/outbound)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/outbound
    ```

    Returns a list of outbound link clicks with their occurrence counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of outbound link objects',
    type: 'OutboundLink[]',
  },
}"
    />

    #### OutboundLink Object [#outboundlink-object]

    <TypeTable
      type="{
  url: {
    description: 'The outbound URL that was clicked',
    type: 'string',
  },
  count: {
    description: 'Number of clicks',
    type: 'number',
  },
  lastClicked: {
    description: 'Most recent click timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events/outbound',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "url": "https://github.com/example/repo",
          "count": 245,
          "lastClicked": "2024-01-31T14:22:00.000Z"
        },
        {
          "url": "https://twitter.com/example",
          "count": 189,
          "lastClicked": "2024-01-31T12:15:00.000Z"
        },
        {
          "url": "https://docs.example.com",
          "count": 156,
          "lastClicked": "2024-01-31T10:30:00.000Z"
        }
      ]
    }
    ```
  </div>
</div>


# Get Event Properties (/docs/api/events/properties)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/properties
    ```

    Returns property key-value pairs for a specific event name with their occurrence counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  event_name: {
    description: 'Event name to get properties for',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of property objects',
    type: 'EventProperty[]',
  },
}"
    />

    #### EventProperty Object [#eventproperty-object]

    <TypeTable
      type="{
  propertyKey: {
    description: 'Property key name',
    type: 'string',
  },
  propertyValue: {
    description: 'Property value',
    type: 'string',
  },
  count: {
    description: 'Number of occurrences',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events/properties',
            params={
                'event_name': 'signup',
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "propertyKey": "plan",
          "propertyValue": "pro",
          "count": 520
        },
        {
          "propertyKey": "plan",
          "propertyValue": "starter",
          "count": 430
        },
        {
          "propertyKey": "plan",
          "propertyValue": "enterprise",
          "count": 300
        },
        {
          "propertyKey": "source",
          "propertyValue": "homepage",
          "count": 650
        },
        {
          "propertyKey": "source",
          "propertyValue": "pricing",
          "count": 600
        }
      ]
    }
    ```
  </div>
</div>


# Get Event Time Series (/docs/api/events/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/time-series
    ```

    Returns time-bucketed counts for the top custom events.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
  },
  limit: {
    description: 'Number of top custom events (by total count) to include',
    type: 'number',
    typeDescription: 'Range: 1-10',
    default: 5,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
  },
  event_name: {
    description: 'Name of the custom event',
    type: 'string',
  },
  event_count: {
    description: 'Number of times the event occurred in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/events/time-series',
            params={
                'bucket': 'hour',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York',
                'limit': 5
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        { "time": "2024-01-15 13:00:00", "event_name": "signup", "event_count": 42 },
        { "time": "2024-01-15 13:00:00", "event_name": "purchase", "event_count": 12 }
      ]
    }
    ```
  </div>
</div>


# Analyze Funnel (/docs/api/funnels/analyze)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/funnels/analyze
    ```

    Analyzes a funnel and returns step-by-step conversion data. Sessions must complete steps in order (step 2 must occur after step 1, etc.).

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Request Body [#request-body]

    <TypeTable
      type="{
  steps: {
    description: 'Array of funnel steps (minimum 2)',
    type: 'FunnelStep[]',
    required: true,
  },
}"
    />

    #### FunnelStep Object [#funnelstep-object]

    <TypeTable
      type="{
  type: {
    description: 'Step type',
    type: 'string',
    typeDescription: '&#x22;page&#x22; | &#x22;event&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;form_submit&#x22; | &#x22;copy&#x22;',
    required: true,
  },
  value: {
    description: 'Page path pattern or event name',
    type: 'string',
    required: true,
  },
  name: {
    description: 'Display name for the step',
    type: 'string',
    required: false,
  },
  hostname: {
    description: 'Filter by specific hostname',
    type: 'string',
    required: false,
  },
  eventPropertyKey: {
    description: 'Event property key to match (for event steps)',
    type: 'string',
    required: false,
  },
  eventPropertyValue: {
    description: 'Event property value to match',
    type: 'string | number | boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of step results',
    type: 'FunnelStepResult[]',
  },
}"
    />

    #### FunnelStepResult Object [#funnelstepresult-object]

    <TypeTable
      type="{
  step_number: {
    description: 'Step number (1-indexed)',
    type: 'number',
  },
  step_name: {
    description: 'Step name',
    type: 'string',
  },
  sessions: {
    description: 'Number of sessions that reached this step',
    type: 'number',
  },
  visitors: {
    description: 'Deprecated alias of `sessions`, kept for backwards compatibility',
    type: 'number',
  },
  conversion_rate: {
    description: 'Percentage of step 1 sessions that reached this step',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  dropoff_rate: {
    description: 'Percentage who dropped off from the previous step',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "steps": [
              { "type": "page", "value": "/", "name": "Homepage" },
              { "type": "page", "value": "/pricing", "name": "Pricing" },
              { "type": "page", "value": "/signup", "name": "Signup" },
              { "type": "event", "value": "signup_complete", "name": "Complete" }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              steps: [
                { type: 'page', value: '/', name: 'Homepage' },
                { type: 'page', value: '/pricing', name: 'Pricing' },
                { type: 'page', value: '/signup', name: 'Signup' },
                { type: 'event', value: 'signup_complete', name: 'Complete' }
              ]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/funnels/analyze',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            json={
                'steps': [
                    { 'type': 'page', 'value': '/', 'name': 'Homepage' },
                    { 'type': 'page', 'value': '/pricing', 'name': 'Pricing' },
                    { 'type': 'page', 'value': '/signup', 'name': 'Signup' },
                    { 'type': 'event', 'value': 'signup_complete', 'name': 'Complete' }
                ]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'steps' => [
                ['type' => 'page', 'value' => '/', 'name' => 'Homepage'],
                ['type' => 'page', 'value' => '/pricing', 'name' => 'Pricing'],
                ['type' => 'page', 'value' => '/signup', 'name' => 'Signup'],
                ['type' => 'event', 'value' => 'signup_complete', 'name' => 'Complete']
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          steps: [
            { type: 'page', value: '/', name: 'Homepage' },
            { type: 'page', value: '/pricing', name: 'Pricing' },
            { type: 'page', value: '/signup', name: 'Signup' },
            { type: 'event', value: 'signup_complete', name: 'Complete' }
          ]
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "bytes"
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            body := map[string]interface{}{
                "steps": []map[string]string{
                    {"type": "page", "value": "/", "name": "Homepage"},
                    {"type": "page", "value": "/pricing", "name": "Pricing"},
                    {"type": "page", "value": "/signup", "name": "Signup"},
                    {"type": "event", "value": "signup_complete", "name": "Complete"},
                },
            }
            jsonBody, _ := json.Marshal(body)

            client := &http.Client{}
            req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31", bytes.NewBuffer(jsonBody))
            req.Header.Set("Authorization", "Bearer your_api_key_here")
            req.Header.Set("Content-Type", "application/json")

            resp, _ := client.Do(req)
            defer resp.Body.Close()

            respBody, _ := io.ReadAll(resp.Body)
            var data map[string]interface{}
            json.Unmarshal(respBody, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::{json, Value};

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let body = json!({
                "steps": [
                    {"type": "page", "value": "/", "name": "Homepage"},
                    {"type": "page", "value": "/pricing", "name": "Pricing"},
                    {"type": "page", "value": "/signup", "name": "Signup"},
                    {"type": "event", "value": "signup_complete", "name": "Complete"}
                ]
            });

            let client = reqwest::Client::new();
            let response = client
                .post("https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31")
                .header("Authorization", "Bearer your_api_key_here")
                .header("Content-Type", "application/json")
                .json(&body)
                .send()
                .await?;

            let data: Value = response.json().await?;
            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        String json = """
        {
          "steps": [
            {"type": "page", "value": "/", "name": "Homepage"},
            {"type": "page", "value": "/pricing", "name": "Pricing"},
            {"type": "page", "value": "/signup", "name": "Signup"},
            {"type": "event", "value": "signup_complete", "name": "Complete"}
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        String data = response.body();
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System.Net.Http;
        using System.Net.Http.Headers;
        using System.Text;
        using System.Text.Json;

        var body = new
        {
            steps = new[]
            {
                new { type = "page", value = "/", name = "Homepage" },
                new { type = "page", value = "/pricing", name = "Pricing" },
                new { type = "page", value = "/signup", name = "Signup" },
                new { type = "event", value = "signup_complete", name = "Complete" }
            }
        };

        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync(
            "https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31",
            content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "step_number": 1,
          "step_name": "Homepage",
          "sessions": 10000,
          "conversion_rate": 100,
          "dropoff_rate": 0
        },
        {
          "step_number": 2,
          "step_name": "Pricing",
          "sessions": 4500,
          "conversion_rate": 45,
          "dropoff_rate": 55
        },
        {
          "step_number": 3,
          "step_name": "Signup",
          "sessions": 1800,
          "conversion_rate": 18,
          "dropoff_rate": 60
        },
        {
          "step_number": 4,
          "step_name": "Complete",
          "sessions": 720,
          "conversion_rate": 7.2,
          "dropoff_rate": 60
        }
      ]
    }
    ```
  </div>
</div>


# Create Funnel (/docs/api/funnels/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/funnels
    ```

    Creates or updates a saved funnel. If `reportId` is provided, updates the existing funnel.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Funnel name',
    type: 'string',
    required: true,
  },
  steps: {
    description: 'Array of funnel steps (minimum 2)',
    type: 'FunnelStep[]',
    required: true,
  },
  reportId: {
    description: 'Existing funnel ID to update (optional)',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the funnel was created/updated',
    type: 'boolean',
  },
  funnelId: {
    description: 'ID of the created/updated funnel',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Create New Funnel"
        curl -X POST "https://app.rybbit.io/api/sites/1/funnels" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Checkout Funnel",
            "steps": [
              { "type": "page", "value": "/products/*", "name": "Product Page" },
              { "type": "page", "value": "/cart", "name": "Cart" },
              { "type": "page", "value": "/checkout", "name": "Checkout" },
              { "type": "event", "value": "purchase", "name": "Purchase" }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Update Existing Funnel"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              reportId: 1,  // Update existing funnel
              name: 'Checkout Funnel (Updated)',
              steps: [
                { type: 'page', value: '/products/*', name: 'Product Page' },
                { type: 'page', value: '/cart', name: 'Cart' },
                { type: 'page', value: '/checkout', name: 'Checkout' },
                { type: 'page', value: '/checkout/success', name: 'Success' }
              ]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/funnels',
            json={
                'name': 'Onboarding Funnel',
                'steps': [
                    { 'type': 'page', 'value': '/signup', 'name': 'Signup' },
                    { 'type': 'event', 'value': 'account_created', 'name': 'Account Created' },
                    { 'type': 'page', 'value': '/onboarding/*', 'name': 'Onboarding' },
                    { 'type': 'event', 'value': 'onboarding_complete', 'name': 'Complete' }
                ]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Checkout Funnel',
            'steps' => [
                ['type' => 'page', 'value' => '/products/*', 'name' => 'Product Page'],
                ['type' => 'page', 'value' => '/cart', 'name' => 'Cart'],
                ['type' => 'page', 'value' => '/checkout', 'name' => 'Checkout'],
                ['type' => 'event', 'value' => 'purchase', 'name' => 'Purchase']
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Checkout Funnel',
          steps: [
            { type: 'page', value: '/products/*', name: 'Product Page' },
            { type: 'page', value: '/cart', name: 'Cart' },
            { type: 'page', value: '/checkout', name: 'Checkout' },
            { type: 'event', value: 'purchase', name: 'Purchase' }
          ]
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Checkout Funnel",
            "steps": []map[string]string{
                {"type": "page", "value": "/products/*", "name": "Product Page"},
                {"type": "page", "value": "/cart", "name": "Cart"},
                {"type": "page", "value": "/checkout", "name": "Checkout"},
                {"type": "event", "value": "purchase", "name": "Purchase"},
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Checkout Funnel",
            "steps": [
                {"type": "page", "value": "/products/*", "name": "Product Page"},
                {"type": "page", "value": "/cart", "name": "Cart"},
                {"type": "page", "value": "/checkout", "name": "Checkout"},
                {"type": "event", "value": "purchase", "name": "Purchase"}
            ]
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/1/funnels")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Checkout Funnel",
          "steps": [
            {"type": "page", "value": "/products/*", "name": "Product Page"},
            {"type": "page", "value": "/cart", "name": "Cart"},
            {"type": "page", "value": "/checkout", "name": "Checkout"},
            {"type": "event", "value": "purchase", "name": "Purchase"}
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Checkout Funnel",
            steps = new[]
            {
                new { type = "page", value = "/products/*", name = "Product Page" },
                new { type = "page", value = "/cart", name = "Cart" },
                new { type = "page", value = "/checkout", name = "Checkout" },
                new { type = "event", value = "purchase", name = "Purchase" }
            }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/funnels", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "funnelId": 2
    }
    ```
  </div>
</div>


# Delete Funnel (/docs/api/funnels/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/funnels/:funnelId
    ```

    Deletes a saved funnel. This action cannot be undone.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  funnelId: {
    description: 'ID of the funnel to delete',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the funnel was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/1/funnels/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels/123',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/1/funnels/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels/123')
        request = Net::HTTP::Delete.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/1/funnels/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/1/funnels/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/1/funnels/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Funnels (/docs/api/funnels/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/funnels
    ```

    Returns all saved funnels for a site.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of saved funnels',
    type: 'Funnel[]',
  },
}"
    />

    #### Funnel Object [#funnel-object]

    <TypeTable
      type="{
  id: {
    description: 'Unique funnel identifier',
    type: 'number',
  },
  name: {
    description: 'Funnel name',
    type: 'string',
  },
  steps: {
    description: 'Array of funnel steps',
    type: 'FunnelStep[]',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/funnels" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/funnels',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels')
        request = Net::HTTP::Get.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            client := &http.Client{}
            req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/funnels", nil)
            req.Header.Set("Authorization", "Bearer your_api_key_here")

            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)
            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();
            let response = client
                .get("https://app.rybbit.io/api/sites/1/funnels")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;
            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        String data = response.body();
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System.Net.Http;
        using System.Net.Http.Headers;

        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "your_api_key_here");

        var response = await client.GetAsync(
            "https://app.rybbit.io/api/sites/1/funnels");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "id": 1,
          "name": "Signup Funnel",
          "steps": [
            { "type": "page", "value": "/", "name": "Homepage" },
            { "type": "page", "value": "/pricing", "name": "Pricing" },
            { "type": "page", "value": "/signup", "name": "Signup" },
            { "type": "page", "value": "/signup/complete", "name": "Complete" }
          ],
          "createdAt": "2024-01-10T12:00:00.000Z",
          "updatedAt": "2024-01-15T09:30:00.000Z"
        }
      ]
    }
    ```
  </div>
</div>


# Get Funnel Step Sessions (/docs/api/funnels/step-sessions)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/funnels/:stepNumber/sessions
    ```

    Returns sessions that either reached or dropped off at a specific funnel step. Useful for analyzing user behavior at each stage.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  stepNumber: {
    description: 'Step number (1-indexed)',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  mode: {
    description: 'Whether to get sessions that reached or dropped off at this step',
    type: 'string',
    typeDescription: '&#x22;reached&#x22; | &#x22;dropped&#x22;',
    required: true,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 25,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  steps: {
    description: 'Array of funnel steps (same as used in analyze)',
    type: 'FunnelStep[]',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session objects',
    type: 'Session[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Get sessions that dropped off at step 2"
        curl -X POST "https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "steps": [
              { "type": "page", "value": "/", "name": "Homepage" },
              { "type": "page", "value": "/pricing", "name": "Pricing" },
              { "type": "page", "value": "/signup", "name": "Signup" }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Get sessions that reached step 3"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels/3/sessions?mode=reached&page=1',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              steps: [
                { type: 'page', value: '/', name: 'Homepage' },
                { type: 'page', value: '/pricing', name: 'Pricing' },
                { type: 'page', value: '/signup', name: 'Signup' }
              ]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/funnels/2/sessions',
            params={
                'mode': 'dropped',
                'page': 1
            },
            json={
                'steps': [
                    { 'type': 'page', 'value': '/', 'name': 'Homepage' },
                    { 'type': 'page', 'value': '/pricing', 'name': 'Pricing' },
                    { 'type': 'page', 'value': '/signup', 'name': 'Signup' }
                ]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'steps' => [
                ['type' => 'page', 'value' => '/', 'name' => 'Homepage'],
                ['type' => 'page', 'value' => '/pricing', 'name' => 'Pricing'],
                ['type' => 'page', 'value' => '/signup', 'name' => 'Signup']
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          steps: [
            { type: 'page', value: '/', name: 'Homepage' },
            { type: 'page', value: '/pricing', name: 'Pricing' },
            { type: 'page', value: '/signup', name: 'Signup' }
          ]
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "steps": []map[string]string{
                {"type": "page", "value": "/", "name": "Homepage"},
                {"type": "page", "value": "/pricing", "name": "Pricing"},
                {"type": "page", "value": "/signup", "name": "Signup"},
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "steps": [
                {"type": "page", "value": "/", "name": "Homepage"},
                {"type": "page", "value": "/pricing", "name": "Pricing"},
                {"type": "page", "value": "/signup", "name": "Signup"}
            ]
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "steps": [
            {"type": "page", "value": "/", "name": "Homepage"},
            {"type": "page", "value": "/pricing", "name": "Pricing"},
            {"type": "page", "value": "/signup", "name": "Signup"}
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            steps = new[]
            {
                new { type = "page", value = "/", name = "Homepage" },
                new { type = "page", value = "/pricing", name = "Pricing" },
                new { type = "page", value = "/signup", name = "Signup" }
            }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync(
            "https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1",
            content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "sess_abc123",
          "user_id": "user_xyz789",
          "country": "US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "entry_page": "/",
          "exit_page": "/pricing",
          "pageviews": 3,
          "session_duration": 125,
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:02:05.000Z",
          "referrer": "https://google.com",
          "channel": "organic"
        }
      ]
    }
    ```
  </div>
</div>


# Create Goal (/docs/api/goals/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/goals
    ```

    Creates a new goal for tracking conversions.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Goal name',
    type: 'string',
    required: false,
  },
  goalType: {
    description: 'Type of goal',
    type: 'string',
    typeDescription: '&#x22;path&#x22; | &#x22;event&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;form_submit&#x22; | &#x22;copy&#x22;',
    required: true,
  },
  config: {
    description: 'Goal configuration',
    type: 'GoalConfig',
    required: true,
  },
}"
    />

    #### GoalConfig for Path Goals [#goalconfig-for-path-goals]

    <TypeTable
      type="{
  pathPattern: {
    description: 'URL path pattern to match. Supports wildcards (*)',
    type: 'string',
    required: true,
    typeDescription: 'e.g., &#x22;/checkout/*&#x22;, &#x22;/signup/complete&#x22;',
  },
}"
    />

    #### GoalConfig for Event Goals [#goalconfig-for-event-goals]

    <TypeTable
      type="{
  eventName: {
    description: 'Event name to match',
    type: 'string',
    required: true,
  },
  eventPropertyKey: {
    description: 'Property key to match (optional)',
    type: 'string',
    required: false,
  },
  eventPropertyValue: {
    description: 'Property value to match (required if key is provided)',
    type: 'string | number | boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the goal was created',
    type: 'boolean',
  },
  goalId: {
    description: 'ID of the created goal',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Path Goal"
        curl -X POST "https://app.rybbit.io/api/sites/1/goals" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Checkout Complete",
            "goalType": "path",
            "config": {
              "pathPattern": "/checkout/success"
            }
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Event Goal"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Purchase Made',
              goalType: 'event',
              config: {
                eventName: 'purchase',
                eventPropertyKey: 'plan',
                eventPropertyValue: 'pro'
              }
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/goals',
            json={
                'name': 'Signup Complete',
                'goalType': 'path',
                'config': {
                    'pathPattern': '/signup/*'
                }
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Checkout Complete',
            'goalType' => 'path',
            'config' => [
                'pathPattern' => '/checkout/success'
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/goals')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Checkout Complete',
          goalType: 'path',
          config: { pathPattern: '/checkout/success' }
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Checkout Complete",
            "goalType": "path",
            "config": map[string]string{
                "pathPattern": "/checkout/success",
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/goals", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Checkout Complete",
            "goalType": "path",
            "config": {
                "pathPattern": "/checkout/success"
            }
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/1/goals")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Checkout Complete",
          "goalType": "path",
          "config": {
            "pathPattern": "/checkout/success"
          }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/goals"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Checkout Complete",
            goalType = "path",
            config = new { pathPattern = "/checkout/success" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/goals", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "goalId": 3
    }
    ```
  </div>
</div>


# Delete Goal (/docs/api/goals/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/goals/:goalId
    ```

    Deletes a goal. This action cannot be undone.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  goalId: {
    description: 'ID of the goal to delete',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the goal was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/1/goals/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals/123',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/1/goals/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/goals/123')
        request = Net::HTTP::Delete.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/1/goals/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/1/goals/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/goals/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/1/goals/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Goals (/docs/api/goals/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/goals
    ```

    Returns a paginated list of goals with their conversion metrics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  page_size: {
    description: 'Number of results per page (max 100)',
    type: 'number',
    default: 10,
  },
  sort: {
    description: 'Field to sort by',
    type: 'string',
    typeDescription: '&#x22;goalId&#x22; | &#x22;name&#x22; | &#x22;goalType&#x22; | &#x22;createdAt&#x22;',
    default: 'createdAt',
  },
  order: {
    description: 'Sort direction',
    type: 'string',
    typeDescription: '&#x22;asc&#x22; | &#x22;desc&#x22;',
    default: 'desc',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of goal objects with conversion data',
    type: 'Goal[]',
  },
  meta: {
    description: 'Pagination metadata',
    type: 'PaginationMeta',
  },
}"
    />

    #### Goal Object [#goal-object]

    <TypeTable
      type="{
  goalId: {
    description: 'Unique goal identifier',
    type: 'number',
  },
  name: {
    description: 'Goal name',
    type: 'string | null',
  },
  goalType: {
    description: 'Type of goal',
    type: 'string',
    typeDescription: '&#x22;path&#x22; | &#x22;event&#x22;',
  },
  config: {
    description: 'Goal configuration',
    type: 'GoalConfig',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  total_conversions: {
    description: 'Number of sessions that completed the goal',
    type: 'number',
  },
  total_sessions: {
    description: 'Total sessions in the time period',
    type: 'number',
  },
  conversion_rate: {
    description: 'Conversion rate (0-1)',
    type: 'number',
  },
}"
    />

    #### GoalConfig Object [#goalconfig-object]

    <TypeTable
      type="{
  pathPattern: {
    description: 'URL path pattern (for path goals). Supports wildcards (*)',
    type: 'string',
    required: false,
  },
  eventName: {
    description: 'Event name to match (for event goals)',
    type: 'string',
    required: false,
  },
  eventPropertyKey: {
    description: 'Event property key to match',
    type: 'string',
    required: false,
  },
  eventPropertyValue: {
    description: 'Event property value to match',
    type: 'string | number | boolean',
    required: false,
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/goals',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        <?php
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ?>
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'
        require 'uri'

        uri = URI('https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(req)
        end

        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            url := "https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31"

            req, _ := http.NewRequest("GET", url, nil)
            req.Header.Add("Authorization", "Bearer your_api_key_here")

            client := &http.Client{}
            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)

            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();

            let response = client
                .get("https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;

            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class Main {
            public static void main(String[] args) throws Exception {
                HttpClient client = HttpClient.newHttpClient();

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31"))
                    .header("Authorization", "Bearer your_api_key_here")
                    .GET()
                    .build();

                HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

                String data = response.body();
            }
        }
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System;
        using System.Net.Http;
        using System.Threading.Tasks;

        class Program
        {
            static async Task Main(string[] args)
            {
                using var client = new HttpClient();

                client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

                var response = await client.GetAsync(
                    "https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31");

                var data = await response.Content.ReadAsStringAsync();
            }
        }
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "goalId": 1,
          "name": "Signup Completed",
          "goalType": "path",
          "config": {
            "pathPattern": "/signup/complete"
          },
          "createdAt": "2024-01-10T12:00:00.000Z",
          "total_conversions": 1250,
          "total_sessions": 15420,
          "conversion_rate": 0.081
        },
        {
          "goalId": 2,
          "name": "Purchase Made",
          "goalType": "event",
          "config": {
            "eventName": "purchase",
            "eventPropertyKey": "value",
            "eventPropertyValue": 100
          },
          "createdAt": "2024-01-15T09:30:00.000Z",
          "total_conversions": 320,
          "total_sessions": 15420,
          "conversion_rate": 0.021
        }
      ],
      "meta": {
        "total": 2,
        "page": 1,
        "pageSize": 10,
        "totalPages": 1
      }
    }
    ```
  </div>
</div>


# Get Goal Sessions (/docs/api/goals/sessions)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/goals/:goalId/sessions
    ```

    Returns sessions that completed a specific goal. Useful for analyzing the behavior of converting users.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  goalId: {
    description: 'Goal ID',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 25,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session objects',
    type: 'Session[]',
  },
}"
    />

    #### Session Object [#session-object]

    <TypeTable
      type="{
  session_id: {
    description: 'Unique session identifier',
    type: 'string',
  },
  user_id: {
    description: 'User identifier',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  entry_page: {
    description: 'First page visited',
    type: 'string',
  },
  exit_page: {
    description: 'Last page visited',
    type: 'string',
  },
  pageviews: {
    description: 'Number of pageviews',
    type: 'number',
  },
  session_duration: {
    description: 'Session duration in seconds',
    type: 'number',
  },
  session_start: {
    description: 'Session start time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  session_end: {
    description: 'Session end time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/goals/1/sessions',
            params={
                'page': 1,
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        <?php
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ?>
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'
        require 'uri'

        uri = URI('https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(req)
        end

        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            url := "https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10"

            req, _ := http.NewRequest("GET", url, nil)
            req.Header.Add("Authorization", "Bearer your_api_key_here")

            client := &http.Client{}
            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)

            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();

            let response = client
                .get("https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;

            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class Main {
            public static void main(String[] args) throws Exception {
                HttpClient client = HttpClient.newHttpClient();

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10"))
                    .header("Authorization", "Bearer your_api_key_here")
                    .GET()
                    .build();

                HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

                String data = response.body();
            }
        }
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System;
        using System.Net.Http;
        using System.Threading.Tasks;

        class Program
        {
            static async Task Main(string[] args)
            {
                using var client = new HttpClient();

                client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

                var response = await client.GetAsync(
                    "https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10");

                var data = await response.Content.ReadAsStringAsync();
            }
        }
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "sess_abc123",
          "user_id": "user_xyz789",
          "country": "US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "entry_page": "/",
          "exit_page": "/signup/complete",
          "pageviews": 5,
          "session_duration": 245,
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:04:05.000Z",
          "referrer": "https://google.com",
          "channel": "organic"
        }
      ]
    }
    ```
  </div>
</div>


# Get Goal Time Series (/docs/api/goals/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/goals/time-series
    ```

    Returns goal conversions and conversion rate over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters) plus the following:

    <TypeTable
      type="{
  goal_ids: {
    description: 'The goals to include',
    type: 'string',
    typeDescription: 'Comma-separated goal IDs (e.g. &#x22;1,2&#x22;) or a JSON array. If omitted, the response is empty.',
    required: true,
  },
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
  },
}"
    />

    #### Bucket Selection Guide [#bucket-selection-guide]

    | Bucket         | Best For                             |
    | -------------- | ------------------------------------ |
    | `minute`       | Real-time monitoring (last hour)     |
    | `five_minutes` | Short-term analysis (last few hours) |
    | `hour`         | Daily analysis                       |
    | `day`          | Weekly/monthly analysis              |
    | `week`         | Monthly/quarterly analysis           |
    | `month`        | Yearly analysis                      |

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  goal_id: {
    description: 'ID of the goal',
    type: 'number',
  },
  conversions: {
    description: 'Number of distinct converting sessions in this bucket',
    type: 'number',
  },
  total_sessions: {
    description: 'Total number of sessions in this bucket',
    type: 'number',
  },
  conversion_rate: {
    description: 'Conversion rate as a fraction',
    type: 'number',
    typeDescription: 'Range: 0-1',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/goals/time-series',
            params={
                'goal_ids': '1,2',
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-01T00:00:00.000Z",
          "goal_id": 1,
          "conversions": 84,
          "total_sessions": 1250,
          "conversion_rate": 0.0672
        },
        {
          "time": "2024-01-02T00:00:00.000Z",
          "goal_id": 1,
          "conversions": 97,
          "total_sessions": 1420,
          "conversion_rate": 0.0683
        }
      ]
    }
    ```
  </div>
</div>


# Update Goal (/docs/api/goals/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:site/goals/:goalId
    ```

    Updates an existing goal.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  goalId: {
    description: 'ID of the goal to update',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Updated goal name',
    type: 'string',
    required: false,
  },
  goalType: {
    description: 'Type of goal',
    type: 'string',
    typeDescription: '&#x22;path&#x22; | &#x22;event&#x22;',
    required: true,
  },
  config: {
    description: 'Updated goal configuration',
    type: 'GoalConfig',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the goal was updated',
    type: 'boolean',
  },
  goalId: {
    description: 'ID of the updated goal',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/sites/1/goals/123" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Signup Completed (Updated)",
            "goalType": "path",
            "config": {
              "pathPattern": "/signup/complete/*"
            }
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals/123',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Signup Completed (Updated)',
              goalType: 'path',
              config: {
                pathPattern: '/signup/complete/*'
              }
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/sites/1/goals/123',
            json={
                'name': 'Signup Completed (Updated)',
                'goalType': 'path',
                'config': {
                    'pathPattern': '/signup/complete/*'
                }
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Signup Completed (Updated)',
            'goalType' => 'path',
            'config' => [
                'pathPattern' => '/signup/complete/*'
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/goals/123')
        request = Net::HTTP::Put.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Signup Completed (Updated)',
          goalType: 'path',
          config: { pathPattern: '/signup/complete/*' }
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Signup Completed (Updated)",
            "goalType": "path",
            "config": map[string]string{
                "pathPattern": "/signup/complete/*",
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("PUT", "https://app.rybbit.io/api/sites/1/goals/123", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Signup Completed (Updated)",
            "goalType": "path",
            "config": {
                "pathPattern": "/signup/complete/*"
            }
        });

        let client = reqwest::Client::new();
        let res = client
            .put("https://app.rybbit.io/api/sites/1/goals/123")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Signup Completed (Updated)",
          "goalType": "path",
          "config": {
            "pathPattern": "/signup/complete/*"
          }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/goals/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Signup Completed (Updated)",
            goalType = "path",
            config = new { pathPattern = "/signup/complete/*" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PutAsync("https://app.rybbit.io/api/sites/1/goals/123", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "goalId": 1
    }
    ```
  </div>
</div>


# Create Import (/docs/api/imports/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/imports
    ```

    Starts a new data import from a supported platform. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    Only one concurrent import is allowed per organization. Starting a second import while one is still running returns HTTP `429`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  platform: {
    description: 'Source platform to import data from',
    type: 'string',
    typeDescription: '&#x22;umami&#x22; | &#x22;simple_analytics&#x22; | &#x22;plausible&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Import details',
    type: 'CreateImportData',
  },
}"
    />

    #### CreateImportData Object [#createimportdata-object]

    <TypeTable
      type="{
  importId: {
    description: 'UUID of the created import. Use this when uploading events.',
    type: 'string',
    typeDescription: 'UUID',
  },
  allowedDateRange: {
    description: 'The inclusive date window you may import events within, based on your plan\'s retention',
    type: 'AllowedDateRange',
  },
}"
    />

    #### AllowedDateRange Object [#alloweddaterange-object]

    <TypeTable
      type="{
  earliestAllowedDate: {
    description: 'Earliest date you may import events for (inclusive)',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
  latestAllowedDate: {
    description: 'Latest date you may import events for (inclusive)',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/123/imports" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "platform": "plausible"
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              platform: 'plausible'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/123/imports',
            json={
                'platform': 'plausible'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'platform' => 'plausible'
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/imports')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          platform: 'plausible'
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "platform": "plausible",
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/123/imports", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "platform": "plausible"
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/123/imports")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "platform": "plausible"
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/imports"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            platform = "plausible"
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/123/imports", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "importId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "allowedDateRange": {
          "earliestAllowedDate": "2023-01-01",
          "latestAllowedDate": "2024-01-31"
        }
      }
    }
    ```
  </div>
</div>


# Delete Import (/docs/api/imports/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/imports/:importId
    ```

    Deletes an import and all events it added. The import must be finished. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    A still-running import cannot be deleted and returns HTTP `400`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  importId: {
    description: 'UUID of the import to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns `200 OK` with an empty body.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479')
        req = Net::HTTP::Delete.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479");
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Upload Import Events (/docs/api/imports/events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/imports/:importId/events
    ```

    Uploads a batch of raw events to an in-progress import. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    Upload events in batches. The request body limit is 50 MB, so split large exports across multiple requests. Set `isLastBatch` to `true` on the final batch to finalize the import.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  importId: {
    description: 'UUID of the import to upload events to',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  events: {
    description: 'Raw, platform-specific event objects whose shape matches the platform chosen when the import was created (Umami, Simple Analytics, or Plausible export rows)',
    type: 'object[]',
    required: true,
  },
  isLastBatch: {
    description: 'Set to true on the final batch to finalize the import',
    type: 'boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns `200 OK` with an empty body. Events outside your plan's retention window are skipped and reflected in the import's `skippedEvents` / `invalidEvents` counts (see [List Imports](/docs/api/imports/list)).
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "events": [
              { "...": "platform-specific fields" }
            ],
            "isLastBatch": false
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              events: [
                { '...': 'platform-specific fields' }
              ],
              isLastBatch: false
            })
          }
        );
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events',
            json={
                'events': [
                    { '...': 'platform-specific fields' }
                ],
                'isLastBatch': False
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'events' => [
                ['...' => 'platform-specific fields']
            ],
            'isLastBatch' => false
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          events: [
            { '...': 'platform-specific fields' }
          ],
          isLastBatch: false
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "events": []map[string]string{
                {"...": "platform-specific fields"},
            },
            "isLastBatch": false,
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "events": [
                {"...": "platform-specific fields"}
            ],
            "isLastBatch": false
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "events": [
            {"...": "platform-specific fields"}
          ],
          "isLastBatch": false
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            events = new[]
            {
                new Dictionary<string, string> { { "...", "platform-specific fields" } }
            },
            isLastBatch = false
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events", content);
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# List Imports (/docs/api/imports/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/imports
    ```

    Returns all data imports for a site with their progress counts. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of import objects',
    type: 'Import[]',
  },
}"
    />

    #### Import Object [#import-object]

    <TypeTable
      type="{
  importId: {
    description: 'Unique import identifier',
    type: 'string',
    typeDescription: 'UUID',
  },
  platform: {
    description: 'Source platform the data was imported from',
    type: 'string',
    typeDescription: '&#x22;umami&#x22; | &#x22;simple_analytics&#x22; | &#x22;plausible&#x22;',
  },
  importedEvents: {
    description: 'Number of events successfully imported',
    type: 'number',
  },
  skippedEvents: {
    description: 'Number of events skipped (e.g. outside the retention window)',
    type: 'number',
  },
  invalidEvents: {
    description: 'Number of events rejected as invalid',
    type: 'number',
  },
  startedAt: {
    description: 'When the import started',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  completedAt: {
    description: 'When the import finished, or null while it is still running',
    type: 'string | null',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/imports" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/imports',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        <?php
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ?>
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'
        require 'uri'

        uri = URI('https://app.rybbit.io/api/sites/123/imports')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(req)
        end

        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            url := "https://app.rybbit.io/api/sites/123/imports"

            req, _ := http.NewRequest("GET", url, nil)
            req.Header.Add("Authorization", "Bearer your_api_key_here")

            client := &http.Client{}
            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)

            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();

            let response = client
                .get("https://app.rybbit.io/api/sites/123/imports")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;

            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class Main {
            public static void main(String[] args) throws Exception {
                HttpClient client = HttpClient.newHttpClient();

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://app.rybbit.io/api/sites/123/imports"))
                    .header("Authorization", "Bearer your_api_key_here")
                    .GET()
                    .build();

                HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

                String data = response.body();
            }
        }
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System;
        using System.Net.Http;
        using System.Threading.Tasks;

        class Program
        {
            static async Task Main(string[] args)
            {
                using var client = new HttpClient();

                client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

                var response = await client.GetAsync(
                    "https://app.rybbit.io/api/sites/123/imports");

                var data = await response.Content.ReadAsStringAsync();
            }
        }
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "importId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
          "platform": "plausible",
          "importedEvents": 15420,
          "skippedEvents": 120,
          "invalidEvents": 3,
          "startedAt": "2024-01-10T12:00:00.000Z",
          "completedAt": "2024-01-10T12:04:30.000Z"
        },
        {
          "importId": "9a1c8f2e-3b7d-4e1a-9c0f-2d5b6a7e8f10",
          "platform": "umami",
          "importedEvents": 8200,
          "skippedEvents": 0,
          "invalidEvents": 0,
          "startedAt": "2024-01-15T09:30:00.000Z",
          "completedAt": null
        }
      ]
    }
    ```
  </div>
</div>


# Get Journeys (/docs/api/insights/journeys)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/journeys
    ```

    Returns the most common page navigation paths (user journeys) within sessions. Useful for understanding how users navigate through your site.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  steps: {
    description: 'Maximum number of steps in the journey (2-10)',
    type: 'number',
    default: 3,
  },
  limit: {
    description: 'Maximum number of journeys to return (1-500)',
    type: 'number',
    default: 100,
  },
  stepFilters: {
    description: 'JSON object to filter specific steps (e.g., {&#x22;0&#x22;: &#x22;/&#x22;})',
    type: 'string',
    typeDescription: 'JSON string mapping step index to required path',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  journeys: {
    description: 'Array of journey objects',
    type: 'Journey[]',
  },
}"
    />

    #### Journey Object [#journey-object]

    <TypeTable
      type="{
  path: {
    description: 'Array of page paths in order',
    type: 'string[]',
  },
  count: {
    description: 'Number of sessions with this journey',
    type: 'number',
  },
  percentage: {
    description: 'Percentage of total sessions',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/journeys',
            params={
                'steps': 4,
                'limit': 20,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "journeys": [
        {
          "path": ["/", "/pricing", "/signup"],
          "count": 1250,
          "percentage": 8.12
        },
        {
          "path": ["/", "/features", "/pricing", "/signup"],
          "count": 890,
          "percentage": 5.78
        },
        {
          "path": ["/blog/getting-started", "/", "/pricing"],
          "count": 650,
          "percentage": 4.22
        },
        {
          "path": ["/", "/docs", "/docs/quickstart"],
          "count": 580,
          "percentage": 3.77
        },
        {
          "path": ["/", "/about", "/contact"],
          "count": 420,
          "percentage": 2.73
        }
      ]
    }
    ```

    ### Filtering by Step [#filtering-by-step]

    You can filter journeys that include specific pages at specific steps:

    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Filter journeys starting from homepage"
        curl -X GET "https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Filter journeys starting from homepage"
        const stepFilters = JSON.stringify({ "0": "/" });

        const response = await fetch(
          `https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=${encodeURIComponent(stepFilters)}`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response with step filter"
    {
      "journeys": [
        {
          "path": ["/", "/pricing", "/signup"],
          "count": 1250,
          "percentage": 12.5
        },
        {
          "path": ["/", "/features", "/pricing"],
          "count": 890,
          "percentage": 8.9
        },
        {
          "path": ["/", "/docs", "/docs/quickstart"],
          "count": 580,
          "percentage": 5.8
        }
      ]
    }
    ```
  </div>
</div>


# Get Retention (/docs/api/insights/retention)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/retention
    ```

    Returns cohort-based retention analysis data. Users are grouped into cohorts based on their first visit, and retention is tracked over subsequent time periods.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  mode: {
    description: 'Retention period granularity',
    type: 'string',
    typeDescription: '&#x22;day&#x22; | &#x22;week&#x22;',
    default: 'week',
  },
  range: {
    description: 'Number of days to analyze (7-365)',
    type: 'number',
    default: 90,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Retention analysis data',
    type: 'RetentionData',
  },
}"
    />

    #### RetentionData Object [#retentiondata-object]

    <TypeTable
      type="{
  cohorts: {
    description: 'Map of cohort periods to retention data',
    type: 'Record<string, CohortData>',
  },
  maxPeriods: {
    description: 'Maximum number of retention periods',
    type: 'number',
  },
  mode: {
    description: 'Retention mode used',
    type: 'string',
    typeDescription: '&#x22;day&#x22; | &#x22;week&#x22;',
  },
  range: {
    description: 'Time range in days',
    type: 'number',
  },
}"
    />

    #### CohortData Object [#cohortdata-object]

    <TypeTable
      type="{
  size: {
    description: 'Number of users in the cohort',
    type: 'number',
  },
  percentages: {
    description: 'Retention percentages for each period (index 0 = period 0, etc.)',
    type: '(number | null)[]',
    typeDescription: 'null indicates no data for that period yet',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/retention?mode=week&range=90" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/retention?mode=week&range=90',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/retention',
            params={
                'mode': 'week',
                'range': 90
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/retention?mode=week&range=90');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/retention?mode=week&range=90')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/retention?mode=week&range=90", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "cohorts": {
          "2024-01-01": {
            "size": 1250,
            "percentages": [100, 45.2, 32.1, 28.5, 25.3, 22.1]
          },
          "2024-01-08": {
            "size": 1420,
            "percentages": [100, 48.5, 35.2, 30.1, 26.8, null]
          },
          "2024-01-15": {
            "size": 1380,
            "percentages": [100, 46.8, 33.5, 29.2, null, null]
          },
          "2024-01-22": {
            "size": 1510,
            "percentages": [100, 44.2, 31.8, null, null, null]
          },
          "2024-01-29": {
            "size": 1290,
            "percentages": [100, 47.1, null, null, null, null]
          }
        },
        "maxPeriods": 5,
        "mode": "week",
        "range": 90
      }
    }
    ```

    ### Understanding Retention Data [#understanding-retention-data]

    The retention data shows how many users from each cohort return in subsequent periods:

    * **Period 0**: Always 100% (the cohort's first visit)
    * **Period 1**: Users who returned 1 week later
    * **Period 2**: Users who returned 2 weeks later
    * etc.

    A `null` value indicates that period hasn't occurred yet for that cohort.

    ### Visualization Example [#visualization-example]

    ```javascript title="Building a Retention Table"
    const { cohorts, maxPeriods } = data.data;

    // Headers: Cohort, Size, Week 0, Week 1, Week 2, ...
    const headers = ['Cohort', 'Size',
      ...Array(maxPeriods + 1).fill(0).map((_, i) => `Week ${i}`)
    ];

    // Rows
    Object.entries(cohorts).forEach(([date, cohort]) => {
      const row = [
        date,
        cohort.size,
        ...cohort.percentages.map(p => p !== null ? `${p}%` : '-')
      ];
      console.log(row.join(' | '));
    });
    ```
  </div>
</div>


# Add Organization Member (/docs/api/organizations/add-member)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/members
    ```

    Adds a user to an organization with a specified role. The user must already exist in the system. Requires admin or owner role in the organization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  email: {
    description: 'Email address of the user to add',
    type: 'string',
    typeDescription: 'Must match an existing user',
    required: true,
  },
  role: {
    description: 'Role to assign to the user',
    type: 'string',
    typeDescription: '&#x22;admin&#x22; | &#x22;member&#x22; | &#x22;owner&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns a success message when the user is added successfully.

    <TypeTable
      type="{
  message: {
    description: 'Success message',
    type: 'string',
  },
}"
    />

    ### Error Responses [#error-responses]

    <TypeTable
      type="{
  '400': {
    description: 'Invalid input (missing fields, invalid role, or user already a member)',
    type: 'object',
  },
  '401': {
    description: 'Unauthorized (not an admin/owner of the organization)',
    type: 'object',
  },
  '404': {
    description: 'User not found',
    type: 'object',
  },
  '500': {
    description: 'Internal server error',
    type: 'object',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_123/members" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"email": "newuser@example.com", "role": "member"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/members`,
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              email: 'newuser@example.com',
              role: 'member'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_123'
        response = requests.post(
            f'https://app.rybbit.io/api/organizations/{organization_id}/members',
            json={
                'email': 'newuser@example.com',
                'role': 'member'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/members");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'email' => 'newuser@example.com',
            'role' => 'member'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/members")
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = {
          email: 'newuser@example.com',
          role: 'member'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_123"
        body := bytes.NewBuffer([]byte(`{
          "email": "newuser@example.com",
          "role": "member"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/"+organizationId+"/members", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_123";
        let client = reqwest::Client::new();
        let res = client
            .post(format!("https://app.rybbit.io/api/organizations/{}/members", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "email": "newuser@example.com",
                "role": "member"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_123";
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"email\": \"newuser@example.com\", \"role\": \"member\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/members"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"email\": \"newuser@example.com\", \"role\": \"member\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"https://app.rybbit.io/api/organizations/{organizationId}/members", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "message": "User added to organization successfully"
    }
    ```

    ```json title="Error Response (400 - Already a Member)"
    {
      "error": "User is already a member of this organization"
    }
    ```

    ```json title="Error Response (404 - User Not Found)"
    {
      "error": "User not found"
    }
    ```

    ```json title="Error Response (401 - Unauthorized)"
    {
      "error": "Unauthorized"
    }
    ```
  </div>
</div>


# Create Site (/docs/api/organizations/create-site)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/sites
    ```

    Creates a new site within an organization. Requires admin or owner role in the organization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID to add the site to',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  domain: {
    description: 'Site domain',
    type: 'string',
    typeDescription: 'Valid domain format (e.g., example.com)',
    required: true,
  },
  name: {
    description: 'Site display name',
    type: 'string',
    required: true,
  },
  public: {
    description: 'Make analytics publicly accessible',
    type: 'boolean',
    default: false,
  },
  saltUserIds: {
    description: 'Salt user IDs for privacy',
    type: 'boolean',
    default: false,
  },
  blockBots: {
    description: 'Block bot traffic',
    type: 'boolean',
    default: true,
  },
  excludedIPs: {
    description: 'Array of IP addresses to exclude from tracking',
    type: 'string[]',
    default: '[]',
  },
  excludedCountries: {
    description: 'Array of ISO country codes to exclude (e.g., [&#x22;US&#x22;, &#x22;GB&#x22;])',
    type: 'string[]',
    default: '[]',
  },
  sessionReplay: {
    description: 'Enable session replay recording',
    type: 'boolean',
    default: false,
  },
  webVitals: {
    description: 'Enable Core Web Vitals tracking',
    type: 'boolean',
    default: false,
  },
  trackErrors: {
    description: 'Enable JavaScript error tracking',
    type: 'boolean',
    default: false,
  },
  trackOutbound: {
    description: 'Track outbound link clicks',
    type: 'boolean',
    default: true,
  },
  trackUrlParams: {
    description: 'Track URL parameters (UTM, etc.)',
    type: 'boolean',
    default: true,
  },
  trackInitialPageView: {
    description: 'Automatically track the initial page view',
    type: 'boolean',
    default: true,
  },
  trackSpaNavigation: {
    description: 'Track SPA navigation events',
    type: 'boolean',
    default: true,
  },
  trackIp: {
    description: 'Store visitor IP addresses',
    type: 'boolean',
    default: false,
  },
  trackButtonClicks: {
    description: 'Track button click events',
    type: 'boolean',
    default: false,
  },
  trackCopy: {
    description: 'Track copy events',
    type: 'boolean',
    default: false,
  },
  trackFormInteractions: {
    description: 'Track form interaction events',
    type: 'boolean',
    default: false,
  },
  tags: {
    description: 'Array of tags for organizing the site',
    type: 'string[]',
    default: '[]',
  },
}"
    />

    ### Response [#response]

    Returns the created site object with the assigned `siteId`.

    <TypeTable
      type="{
  siteId: {
    description: 'Numeric site ID (auto-assigned)',
    type: 'number',
  },
  id: {
    description: 'Site UUID',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string',
  },
  createdBy: {
    description: 'User ID who created the site',
    type: 'string',
  },
  public: {
    description: 'Whether analytics are public',
    type: 'boolean',
  },
  saltUserIds: {
    description: 'Whether user IDs are salted',
    type: 'boolean',
  },
  blockBots: {
    description: 'Whether bot traffic is blocked',
    type: 'boolean',
  },
  excludedIPs: {
    description: 'Excluded IP addresses',
    type: 'string[]',
  },
  excludedCountries: {
    description: 'Excluded country codes',
    type: 'string[]',
  },
  sessionReplay: {
    description: 'Whether session replay is enabled',
    type: 'boolean',
  },
  webVitals: {
    description: 'Whether Web Vitals tracking is enabled',
    type: 'boolean',
  },
  trackErrors: {
    description: 'Whether error tracking is enabled',
    type: 'boolean',
  },
  trackOutbound: {
    description: 'Whether outbound link tracking is enabled',
    type: 'boolean',
  },
  trackUrlParams: {
    description: 'Whether URL parameter tracking is enabled',
    type: 'boolean',
  },
  trackInitialPageView: {
    description: 'Whether initial page view is tracked automatically',
    type: 'boolean',
  },
  trackSpaNavigation: {
    description: 'Whether SPA navigation is tracked',
    type: 'boolean',
  },
  trackIp: {
    description: 'Whether IP addresses are stored',
    type: 'boolean',
  },
  trackButtonClicks: {
    description: 'Whether button clicks are tracked',
    type: 'boolean',
  },
  trackCopy: {
    description: 'Whether copy events are tracked',
    type: 'boolean',
  },
  trackFormInteractions: {
    description: 'Whether form interactions are tracked',
    type: 'boolean',
  },
  tags: {
    description: 'Site tags',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_123/sites" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"domain": "example.com", "name": "My Website", "blockBots": true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/sites`,
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              domain: 'example.com',
              name: 'My Website',
              blockBots: true
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_123'
        response = requests.post(
            f'https://app.rybbit.io/api/organizations/{organization_id}/sites',
            json={
                'domain': 'example.com',
                'name': 'My Website',
                'blockBots': True
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/sites");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'domain' => 'example.com',
            'name' => 'My Website',
            'blockBots' => true
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/sites")
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = {
          domain: 'example.com',
          name: 'My Website',
          blockBots: true
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_123"
        body := bytes.NewBuffer([]byte(`{
          "domain": "example.com",
          "name": "My Website",
          "blockBots": true
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/"+organizationId+"/sites", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_123";
        let client = reqwest::Client::new();
        let res = client
            .post(format!("https://app.rybbit.io/api/organizations/{}/sites", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "domain": "example.com",
                "name": "My Website",
                "blockBots": true
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_123";
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"domain\": \"example.com\", \"name\": \"My Website\", \"blockBots\": true}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/sites"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"domain\": \"example.com\", \"name\": \"My Website\", \"blockBots\": true}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"https://app.rybbit.io/api/organizations/{organizationId}/sites", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "siteId": 456,
      "id": "a1b2c3d4e5f6",
      "domain": "example.com",
      "name": "My Website",
      "organizationId": "org_123",
      "createdBy": "user_xyz789",
      "public": false,
      "saltUserIds": false,
      "blockBots": true,
      "excludedIPs": [],
      "excludedCountries": [],
      "sessionReplay": false,
      "webVitals": false,
      "trackErrors": false,
      "trackOutbound": true,
      "trackUrlParams": true,
      "trackInitialPageView": true,
      "trackSpaNavigation": true,
      "trackIp": false,
      "trackButtonClicks": false,
      "trackCopy": false,
      "trackFormInteractions": false,
      "tags": []
    }
    ```
  </div>
</div>


# Get Organization Event Count (/docs/api/organizations/event-count)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/org-event-count/:organizationId
    ```

    Returns daily event usage counts across an organization's sites.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  start_date: {
    description: 'Start of the date range. Omit start/end to get all-time daily counts.',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
  end_date: {
    description: 'End of the date range. Omit start/end to get all-time daily counts.',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
  time_zone: {
    description: 'IANA timezone used to bucket events into days',
    type: 'string',
    default: 'UTC',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  event_date: {
    description: 'The day the counts apply to',
    type: 'string',
  },
  pageview_count: {
    description: 'Number of pageview events',
    type: 'number',
  },
  custom_event_count: {
    description: 'Number of custom events',
    type: 'number',
  },
  performance_count: {
    description: 'Number of performance events',
    type: 'number',
  },
  outbound_count: {
    description: 'Number of outbound link events',
    type: 'number',
  },
  error_count: {
    description: 'Number of error events',
    type: 'number',
  },
  button_click_count: {
    description: 'Number of button click events',
    type: 'number',
  },
  copy_count: {
    description: 'Number of copy events',
    type: 'number',
  },
  form_submit_count: {
    description: 'Number of form submit events',
    type: 'number',
  },
  input_change_count: {
    description: 'Number of input change events',
    type: 'number',
  },
  event_count: {
    description: 'Total number of events for the day',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/org-event-count/org_abc123?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/org-event-count/${organizationId}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.get(
            f'https://app.rybbit.io/api/org-event-count/{organization_id}',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'UTC'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/org-event-count/{$organizationId}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/org-event-count/#{organization_id}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/org-event-count/"+organizationId+"?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/org-event-count/{}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/org-event-count/" + organizationId + "?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/org-event-count/{organizationId}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "event_date": "2024-01-01",
          "pageview_count": 38900,
          "custom_event_count": 4210,
          "performance_count": 12050,
          "outbound_count": 980,
          "error_count": 145,
          "button_click_count": 6320,
          "copy_count": 410,
          "form_submit_count": 220,
          "input_change_count": 1530,
          "event_count": 64765
        },
        {
          "event_date": "2024-01-02",
          "pageview_count": 41200,
          "custom_event_count": 4560,
          "performance_count": 12880,
          "outbound_count": 1040,
          "error_count": 132,
          "button_click_count": 6710,
          "copy_count": 455,
          "form_submit_count": 248,
          "input_change_count": 1622,
          "event_count": 68847
        }
      ]
    }
    ```
  </div>
</div>


# Invite Member (/docs/api/organizations/invite-member)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/organization/invite-member
    ```

    Sends an invitation email inviting a user to join an organization with a given role. (To add an existing user directly without an email invite, see Add Member.)

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  email: {
    description: 'Email address of the user to invite',
    type: 'string',
    required: true,
  },
  role: {
    description: 'Role(s) to assign. One of `owner`, `admin`, `member` (or an array of roles).',
    type: 'string | string[]',
    required: true,
  },
  organizationId: {
    description: 'The organization to invite into. Defaults to your active organization.',
    type: 'string',
    required: false,
  },
  resend: {
    description: 'Resend the invitation if the user was already invited.',
    type: 'boolean',
    required: false,
  },
  teamId: {
    description: 'Team ID(s) to add the invited user to.',
    type: 'string | string[]',
    required: false,
  },
  hasRestrictedSiteAccess: {
    description: 'Rybbit extension: restrict the invited member to specific sites. Only valid when role is `member`.',
    type: 'boolean',
    required: false,
  },
  siteIds: {
    description: 'Rybbit extension: the site IDs the member may access when `hasRestrictedSiteAccess` is true.',
    type: 'number[]',
    required: false,
  },
}"
    />

    <Callout>
      `hasRestrictedSiteAccess`

       and 

      `siteIds`

       are Rybbit-specific extensions to the invitation. Site-access restrictions can only be applied to invitations with the 

      `member`

       role.
    </Callout>

    ### Response [#response]

    Returns the created invitation object.

    <TypeTable
      type="{
  id: {
    description: &#x22;The invitation's identifier&#x22;,
    type: 'string',
  },
  email: {
    description: 'Invited email address',
    type: 'string',
  },
  role: {
    description: 'Assigned role',
    type: 'string',
  },
  organizationId: {
    description: 'The organization the invite is for',
    type: 'string',
  },
  inviterId: {
    description: 'ID of the user who sent the invite',
    type: 'string',
  },
  status: {
    description: 'Invitation status (e.g. pending)',
    type: 'string',
  },
  expiresAt: {
    description: 'When the invitation expires',
    type: 'string',
  },
  hasRestrictedSiteAccess: {
    description: 'Whether the member will be restricted to specific sites',
    type: 'boolean',
  },
  siteIds: {
    description: 'Site IDs the member will be allowed to access',
    type: 'number[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/organization/invite-member" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"email": "teammate@example.com", "role": "member"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/organization/invite-member',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              email: 'teammate@example.com',
              role: 'member'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/organization/invite-member',
            json={
                'email': 'teammate@example.com',
                'role': 'member'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/organization/invite-member");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'email' => 'teammate@example.com',
            'role' => 'member'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/organization/invite-member")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          email: 'teammate@example.com',
          role: 'member'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "email": "teammate@example.com",
          "role": "member"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/organization/invite-member", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/organization/invite-member")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "email": "teammate@example.com",
                "role": "member"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"email\": \"teammate@example.com\", \"role\": \"member\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/organization/invite-member"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"email\": \"teammate@example.com\", \"role\": \"member\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/organization/invite-member", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "inv_4a2b...",
      "email": "teammate@example.com",
      "role": "member",
      "organizationId": "org_123",
      "inviterId": "user_2a9b...",
      "status": "pending",
      "expiresAt": "2026-07-03T12:00:00.000Z",
      "hasRestrictedSiteAccess": false,
      "siteIds": []
    }
    ```
  </div>
</div>


# Get My Organizations (/docs/api/organizations/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations
    ```

    Returns all organizations the authenticated user is a member of, including all members for each organization. Excludes subscription and billing information. Supports both session cookies and API key (Bearer token) authentication.

    <Callout type="warn">
      The 

      `members`

       roster is only populated for session-cookie (dashboard) requests. API key / Bearer callers receive 

      `members: []`

       for every organization — use 

      [GET /organizations/:id/members](/docs/api/organizations/members)

       to retrieve member data with a key.
    </Callout>

    ### Response [#response]

    Returns an array of organization objects.

    <TypeTable
      type="{
  id: {
    description: 'Organization ID',
    type: 'string',
  },
  name: {
    description: 'Organization name',
    type: 'string',
  },
  slug: {
    description: 'Organization slug',
    type: 'string',
  },
  logo: {
    description: 'Organization logo URL',
    type: 'string | null',
  },
  createdAt: {
    description: 'Organization creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  role: {
    description: 'Your role in the organization',
    type: 'string',
    typeDescription: '&#x22;owner&#x22; | &#x22;admin&#x22; | &#x22;member&#x22;',
  },
  members: {
    description: 'Array of organization members',
    type: 'array',
  },
  sites: {
    description: 'Array of sites in the organization',
    type: 'array',
  },
}"
    />

    #### Member Object [#member-object]

    Each member in the `members` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Member record ID',
    type: 'string',
  },
  role: {
    description: 'Member role in the organization',
    type: 'string',
    typeDescription: '&#x22;owner&#x22; | &#x22;admin&#x22; | &#x22;member&#x22;',
  },
  userId: {
    description: 'User ID',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when member was added',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  user: {
    description: 'User details',
    type: 'object',
  },
}"
    />

    #### User Object [#user-object]

    <TypeTable
      type="{
  id: {
    description: 'User ID',
    type: 'string',
  },
  name: {
    description: 'User display name',
    type: 'string',
  },
  email: {
    description: 'User email address',
    type: 'string',
  },
}"
    />

    #### Site Object [#site-object]

    Each site in the `sites` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Site ID',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string',
  },
  createdBy: {
    description: 'User ID who created the site',
    type: 'string',
  },
  public: {
    description: 'Whether analytics are publicly accessible',
    type: 'boolean',
  },
  saltUserIds: {
    description: 'Whether user IDs are salted',
    type: 'boolean',
  },
  blockBots: {
    description: 'Whether bot traffic is blocked',
    type: 'boolean',
  },
  createdAt: {
    description: 'Site creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/organizations',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/organizations')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data []map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/organizations")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/organizations");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    [
      {
        "id": "org_123",
        "name": "Acme Inc",
        "slug": "acme-inc",
        "logo": "https://example.com/logo.png",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "role": "owner",
        "members": [
          {
            "id": "member_abc123",
            "role": "owner",
            "userId": "user_xyz789",
            "createdAt": "2024-01-15T10:30:00.000Z",
            "user": {
              "id": "user_xyz789",
              "name": "John Doe",
              "email": "john@example.com"
            }
          },
          {
            "id": "member_def456",
            "role": "member",
            "userId": "user_abc456",
            "createdAt": "2024-02-20T14:15:00.000Z",
            "user": {
              "id": "user_abc456",
              "name": "Jane Smith",
              "email": "jane@example.com"
            }
          }
        ],
        "sites": [
          {
            "id": "456",
            "domain": "example.com",
            "name": "My Website",
            "organizationId": "org_123",
            "createdBy": "user_xyz789",
            "public": false,
            "saltUserIds": false,
            "blockBots": true,
            "createdAt": "2024-01-15T10:30:00.000Z"
          }
        ]
      },
      {
        "id": "org_456",
        "name": "Tech Startup",
        "slug": "tech-startup",
        "logo": null,
        "createdAt": "2024-03-10T08:00:00.000Z",
        "role": "admin",
        "members": [
          {
            "id": "member_ghi789",
            "role": "owner",
            "userId": "user_owner123",
            "createdAt": "2024-03-10T08:00:00.000Z",
            "user": {
              "id": "user_owner123",
              "name": "Alice Johnson",
              "email": "alice@techstartup.com"
            }
          },
          {
            "id": "member_jkl012",
            "role": "admin",
            "userId": "user_xyz789",
            "createdAt": "2024-03-12T09:30:00.000Z",
            "user": {
              "id": "user_xyz789",
              "name": "John Doe",
              "email": "john@example.com"
            }
          }
        ],
        "sites": [
          {
            "id": "789",
            "domain": "techstartup.com",
            "name": "Tech Startup Website",
            "organizationId": "org_456",
            "createdBy": "user_owner123",
            "public": true,
            "saltUserIds": false,
            "blockBots": true,
            "createdAt": "2024-03-10T08:00:00.000Z"
          }
        ]
      }
    ]
    ```
  </div>
</div>


# Get Organization Members (/docs/api/organizations/members)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations/:organizationId/members
    ```

    Returns all members of an organization with their user details and roles. Requires membership in the organization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  data: {
    description: 'Array of organization members',
    type: 'array',
  },
}"
    />

    #### Member Object [#member-object]

    Each member in the `data` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Member record ID',
    type: 'string',
  },
  role: {
    description: 'Member role in the organization',
    type: 'string',
    typeDescription: '&#x22;owner&#x22; | &#x22;admin&#x22; | &#x22;member&#x22;',
  },
  userId: {
    description: 'User ID',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when member was added',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  user: {
    description: 'User details',
    type: 'object',
  },
  siteAccess: {
    description: &#x22;The member's site-access restrictions within the organization&#x22;,
    type: 'object',
  },
  teams: {
    description: 'Teams the member belongs to',
    type: 'array',
  },
}"
    />

    #### User Object [#user-object]

    <TypeTable
      type="{
  id: {
    description: 'User ID',
    type: 'string',
  },
  name: {
    description: 'User display name',
    type: 'string',
  },
  email: {
    description: 'User email address',
    type: 'string',
  },
}"
    />

    #### Site Access Object [#site-access-object]

    <TypeTable
      type="{
  hasRestrictedSiteAccess: {
    description: 'Whether the member is restricted to specific sites',
    type: 'boolean',
  },
  siteIds: {
    description: 'IDs of the sites the member can access (empty when access is not restricted)',
    type: 'array',
  },
}"
    />

    #### Team Object [#team-object]

    Each team in the `teams` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Team ID',
    type: 'string',
  },
  name: {
    description: 'Team name',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations/org_123/members" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/members`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_123'
        response = requests.get(
            f'https://app.rybbit.io/api/organizations/{organization_id}/members',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/members");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/members")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations/"+organizationId+"/members", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/organizations/{}/members", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/members"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/organizations/{organizationId}/members");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": [
        {
          "id": "member_abc123",
          "role": "owner",
          "userId": "user_xyz789",
          "organizationId": "org_123",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "user": {
            "id": "user_xyz789",
            "name": "John Doe",
            "email": "john@example.com"
          },
          "siteAccess": {
            "hasRestrictedSiteAccess": false,
            "siteIds": []
          },
          "teams": []
        },
        {
          "id": "member_def456",
          "role": "member",
          "userId": "user_abc456",
          "organizationId": "org_123",
          "createdAt": "2024-02-20T14:15:00.000Z",
          "user": {
            "id": "user_abc456",
            "name": "Jane Smith",
            "email": "jane@example.com"
          },
          "siteAccess": {
            "hasRestrictedSiteAccess": true,
            "siteIds": ["456"]
          },
          "teams": [
            {
              "id": "team_789",
              "name": "Marketing"
            }
          ]
        }
      ]
    }
    ```
  </div>
</div>


# Remove Member (/docs/api/organizations/remove-member)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/organization/remove-member
    ```

    Removes a member from an organization. The member can be identified by member ID or email.

    <Callout type="warn">
      This endpoint uses 

      **POST**

      , not HTTP DELETE. You cannot remove the only remaining owner of an organization.
    </Callout>

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  memberIdOrEmail: {
    description: &#x22;The member's ID or email address&#x22;,
    type: 'string',
    required: true,
  },
  organizationId: {
    description: 'The organization to remove from. Defaults to your active organization.',
    type: 'string',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the removed member object.

    <TypeTable
      type="{
  member: {
    description: 'The member that was removed',
    type: 'Member',
  },
}"
    />

    #### Member Object [#member-object]

    <TypeTable
      type="{
  id: {
    description: &#x22;The member record's identifier&#x22;,
    type: 'string',
  },
  userId: {
    description: &#x22;The underlying user's ID&#x22;,
    type: 'string',
  },
  organizationId: {
    description: 'The organization the member belonged to',
    type: 'string',
  },
  role: {
    description: &#x22;The member's role&#x22;,
    type: 'string',
  },
  createdAt: {
    description: 'When the membership was created',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/organization/remove-member" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"memberIdOrEmail": "teammate@example.com"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/organization/remove-member',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              memberIdOrEmail: 'teammate@example.com'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/organization/remove-member',
            json={
                'memberIdOrEmail': 'teammate@example.com'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/organization/remove-member");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'memberIdOrEmail' => 'teammate@example.com'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/organization/remove-member")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          memberIdOrEmail: 'teammate@example.com'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "memberIdOrEmail": "teammate@example.com"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/organization/remove-member", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/organization/remove-member")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "memberIdOrEmail": "teammate@example.com"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"memberIdOrEmail\": \"teammate@example.com\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/organization/remove-member"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"memberIdOrEmail\": \"teammate@example.com\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/organization/remove-member", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "member": {
        "id": "mem_7c6d...",
        "userId": "user_5f4g...",
        "organizationId": "org_123",
        "role": "member",
        "createdAt": "2026-01-10T12:00:00.000Z"
      }
    }
    ```
  </div>
</div>


# Get Organization Sites (/docs/api/organizations/sites)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations/:organizationId/sites
    ```

    Returns all sites in an organization the caller can access, with usage and subscription info.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  organization: {
    description: 'The organization record, or null',
    type: 'object | null',
  },
  sites: {
    description: 'Array of site objects',
    type: 'array',
  },
  subscription: {
    description: 'Usage and subscription details for the organization',
    type: 'object',
  },
}"
    />

    #### Site Object [#site-object]

    Each site in the `sites` array contains the following fields. Other site-config fields may also be present:

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'number',
  },
  name: {
    description: 'Site display name',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  type: {
    description: 'Site type',
    type: 'string',
    typeDescription: 'e.g. &#x22;web&#x22;',
  },
  public: {
    description: 'Whether the site dashboard is public',
    type: 'boolean',
  },
  organizationId: {
    description: 'Organization ID the site belongs to',
    type: 'string',
  },
  sessionsLast24Hours: {
    description: 'Number of sessions in the last 24 hours',
    type: 'number',
  },
  isOwner: {
    description: 'Whether the caller owns the site',
    type: 'boolean',
  },
  teams: {
    description: 'Teams the site belongs to',
    type: 'array',
    typeDescription: 'Array of { id, name }',
  },
}"
    />

    #### Subscription Object [#subscription-object]

    <TypeTable
      type="{
  monthlyEventCount: {
    description: 'Events recorded in the current month',
    type: 'number',
  },
  eventLimit: {
    description: 'Monthly event limit for the plan',
    type: 'number',
  },
  overMonthlyLimit: {
    description: 'Whether the monthly event limit has been exceeded',
    type: 'boolean',
  },
  planName: {
    description: 'Name of the active plan',
    type: 'string',
  },
  status: {
    description: 'Subscription status',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations/org_abc123/sites" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/sites`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.get(
            f'https://app.rybbit.io/api/organizations/{organization_id}/sites',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/sites");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/sites")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations/"+organizationId+"/sites", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/organizations/{}/sites", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/sites"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/organizations/{organizationId}/sites");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "organization": {
        "id": "org_abc123",
        "name": "Acme Inc",
        "slug": "acme",
        "createdAt": "2024-01-15T10:30:00.000Z"
      },
      "sites": [
        {
          "siteId": 123,
          "name": "Acme Marketing",
          "domain": "acme.com",
          "type": "web",
          "public": false,
          "organizationId": "org_abc123",
          "sessionsLast24Hours": 842,
          "isOwner": true,
          "teams": [
            {
              "id": "team_xyz789",
              "name": "Growth"
            }
          ]
        }
      ],
      "subscription": {
        "monthlyEventCount": 482910,
        "eventLimit": 1000000,
        "overMonthlyLimit": false,
        "planName": "Pro",
        "status": "active"
      }
    }
    ```
  </div>
</div>


# Update Member Role (/docs/api/organizations/update-member-role)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/organization/update-member-role
    ```

    Updates the role(s) assigned to an existing organization member.

    <Callout>
      This endpoint uses 

      **POST**

      , not PUT or PATCH.
    </Callout>

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  role: {
    description: 'The new role(s) to assign. One of `owner`, `admin`, `member` (or an array of roles).',
    type: 'string | string[]',
    required: true,
  },
  memberId: {
    description: 'The ID of the member to update',
    type: 'string',
    required: true,
  },
  organizationId: {
    description: 'The organization the member belongs to. Defaults to your active organization.',
    type: 'string',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the updated member object directly — the fields are at the top level, **not** nested under a `member` key.

    <TypeTable
      type="{
  id: {
    description: &#x22;The member record's identifier&#x22;,
    type: 'string',
  },
  userId: {
    description: &#x22;The underlying user's ID&#x22;,
    type: 'string',
  },
  organizationId: {
    description: 'The organization the member belongs to',
    type: 'string',
  },
  role: {
    description: &#x22;The member's updated role&#x22;,
    type: 'string',
  },
  createdAt: {
    description: 'When the membership was created',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/organization/update-member-role" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"memberId": "mem_7c6d5e4f3g2h", "role": "admin"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/organization/update-member-role',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              memberId: 'mem_7c6d5e4f3g2h',
              role: 'admin'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/organization/update-member-role',
            json={
                'memberId': 'mem_7c6d5e4f3g2h',
                'role': 'admin'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/organization/update-member-role");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'memberId' => 'mem_7c6d5e4f3g2h',
            'role' => 'admin'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/organization/update-member-role")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          memberId: 'mem_7c6d5e4f3g2h',
          role: 'admin'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "memberId": "mem_7c6d5e4f3g2h",
          "role": "admin"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/organization/update-member-role", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/organization/update-member-role")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "memberId": "mem_7c6d5e4f3g2h",
                "role": "admin"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"memberId\": \"mem_7c6d5e4f3g2h\", \"role\": \"admin\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/organization/update-member-role"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"memberId\": \"mem_7c6d5e4f3g2h\", \"role\": \"admin\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/organization/update-member-role", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "mem_7c6d5e4f3g2h",
      "userId": "user_5f4g...",
      "organizationId": "org_123",
      "role": "admin",
      "createdAt": "2026-01-10T12:00:00.000Z"
    }
    ```
  </div>
</div>


# Get Live Visitors (/docs/api/overview/live-visitors)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/live-user-count
    ```

    Returns the count of unique active visitors within the specified time window. Useful for displaying real-time visitor counts.

    Visitors are counted by identity where one is available (see [Identify Users](/docs/identify-users)) and by anonymous device otherwise, so one person who starts a second session inside the window still counts once.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  minutes: {
    description: 'Time window in minutes to count active visitors',
    type: 'number',
    default: 5,
    typeDescription: 'Visitors with activity within the last N minutes are considered &#x22;live&#x22;',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  count: {
    description: 'Number of unique active visitors',
    type: 'number',
  },
}"
    />

    #### Time Window Guide [#time-window-guide]

    | Minutes | Use Case                                  |
    | ------- | ----------------------------------------- |
    | `1`     | Very active visitors (currently browsing) |
    | `5`     | Standard "live" count (default)           |
    | `15`    | Recently active visitors                  |
    | `30`    | Short-term engagement window              |
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/live-user-count?minutes=5" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/live-user-count?minutes=5',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const { count } = await response.json();
        console.log(`Live visitors: ${count}`);
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/live-user-count',
            params={'minutes': 5},
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        print(f"Live visitors: {data['count']}")
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/live-user-count?minutes=5');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        echo "Live visitors: " . $data['count'];
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/live-user-count?minutes=5')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        puts "Live visitors: #{data['count']}"
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/live-user-count?minutes=5", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        fmt.Printf("Live visitors: %v\n", data["count"])
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/live-user-count?minutes=5")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        println!("Live visitors: {}", data["count"]);
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/live-user-count?minutes=5"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/live-user-count?minutes=5");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "count": 42
    }
    ```

    ### Polling Example [#polling-example]

    ```javascript title="Real-time Widget"
    async function updateLiveCount() {
      const response = await fetch(
        'https://app.rybbit.io/api/sites/123/live-user-count?minutes=5',
        {
          headers: {
            'Authorization': 'Bearer your_api_key'
          }
        }
      );
      const { count } = await response.json();
      document.getElementById('live-visitors')
        .textContent = count;
    }

    // Update every 15 seconds
    setInterval(updateLiveCount, 15000);
    ```
  </div>
</div>


# Get Metric (/docs/api/overview/metric)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/metric
    ```

    Returns dimensional analytics data broken down by a specific parameter. Supports pagination.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  parameter: {
    description: 'The dimension to break down by',
    type: 'FilterParameter',
    typeDescription: 'e.g., &#x22;pathname&#x22;, &#x22;country&#x22;, &#x22;browser&#x22;, &#x22;event_name&#x22;',
    required: true,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of metric results',
    type: 'MetricItem[]',
    typeDescription: 'See MetricItem structure below',
  },
  totalCount: {
    description: 'Total number of unique values across all pages',
    type: 'number',
  },
}"
    />

    #### MetricItem Structure [#metricitem-structure]

    <TypeTable
      type="{
  value: {
    description: 'The dimension value',
    type: 'string',
    typeDescription: 'e.g., &#x22;/blog&#x22;, &#x22;Chrome&#x22;, &#x22;US&#x22;',
  },
  count: {
    description: 'Number of unique sessions for this value. For parameter=event_name, this is the total number of event occurrences instead',
    type: 'number',
  },
  percentage: {
    description: 'Percentage of total sessions',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  pageviews: {
    description: 'Total pageviews (for page-related parameters)',
    type: 'number',
    required: false,
  },
  pageviews_percentage: {
    description: 'Share of total pageviews (for page-related parameters)',
    type: 'number',
    typeDescription: 'Range: 0-100',
    required: false,
  },
  bounce_rate: {
    description: 'Bounce rate percentage',
    type: 'number',
    typeDescription: 'Range: 0-100',
    required: false,
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/metric',
            params={
                'parameter': 'country',
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York',
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "data": [
          {
            "value": "US",
            "count": 8420,
            "percentage": 54.63,
            "pageviews": 26891,
            "pageviews_percentage": 54.96,
            "bounce_rate": 41.2
          },
          {
            "value": "GB",
            "count": 2150,
            "percentage": 13.95,
            "pageviews": 6847,
            "pageviews_percentage": 13.99,
            "bounce_rate": 43.8
          }
        ],
        "totalCount": 87
      }
    }
    ```
  </div>
</div>


# Get Overview (/docs/api/overview/overview)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/overview
    ```

    Returns high-level analytics metrics for a site.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  sessions: {
    description: 'Total number of sessions',
    type: 'number',
  },
  pageviews: {
    description: 'Total number of pageviews',
    type: 'number',
  },
  users: {
    description: 'Total unique users',
    type: 'number',
  },
  pages_per_session: {
    description: 'Average pages viewed per session',
    type: 'number',
  },
  bounce_rate: {
    description: 'Percentage of single-page sessions',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  session_duration: {
    description: 'Average session duration in seconds',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/overview',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "sessions": 15420,
        "pageviews": 48933,
        "users": 12847,
        "pages_per_session": 3.17,
        "bounce_rate": 42.8,
        "session_duration": 182.5
      }
    }
    ```
  </div>
</div>


# Get Page Titles (/docs/api/overview/page-titles)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/page-titles
    ```

    Returns page-view metrics aggregated by HTML page title.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    <TypeTable
      type="{
  limit: {
    description: 'Maximum number of page titles to return',
    type: 'number',
    default: 10,
  },
  page: {
    description: 'Page number (1-indexed). When provided, the response is paginated and includes a total count',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  value: {
    description: 'The page title',
    type: 'string',
  },
  pathname: {
    description: 'A representative path for the title',
    type: 'string',
  },
  count: {
    description: 'Unique sessions that viewed the title',
    type: 'number',
  },
  percentage: {
    description: 'Share of total',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  pageviews: {
    description: 'Total pageviews',
    type: 'number',
  },
  bounce_rate: {
    description: 'Bounce rate percentage',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  time_on_page_seconds: {
    description: 'Average time on page in seconds',
    type: 'number',
  },
}"
    />

    When the `page` parameter is supplied, the response is paginated: `data` becomes an object `{ data: [...], totalCount: number }`.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/page-titles',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York',
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "value": "Home | Acme",
          "pathname": "/",
          "count": 8200,
          "percentage": 41.2,
          "pageviews": 12400,
          "bounce_rate": 38.5,
          "time_on_page_seconds": 47.2
        }
      ]
    }
    ```
  </div>
</div>


# Get Overview (Time Series) (/docs/api/overview/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/overview/time-series
    ```

    Returns time-series analytics data broken down by configurable time buckets. Useful for charting trends over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    required: false,
    default: 'hour',
  },
}"
    />

    #### Bucket Selection Guide [#bucket-selection-guide]

    | Bucket         | Best For                             |
    | -------------- | ------------------------------------ |
    | `minute`       | Real-time monitoring (last hour)     |
    | `five_minutes` | Short-term analysis (last few hours) |
    | `hour`         | Daily analysis                       |
    | `day`          | Weekly/monthly analysis              |
    | `week`         | Monthly/quarterly analysis           |
    | `month`        | Yearly analysis                      |

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'Datetime string, &#x22;YYYY-MM-DD HH:MM:SS&#x22;',
  },
  sessions: {
    description: 'Number of sessions in this bucket',
    type: 'number',
  },
  pageviews: {
    description: 'Number of pageviews in this bucket',
    type: 'number',
  },
  users: {
    description: 'Unique users in this bucket',
    type: 'number',
  },
  pages_per_session: {
    description: 'Average pages viewed per session',
    type: 'number',
  },
  bounce_rate: {
    description: 'Percentage of single-page sessions',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  session_duration: {
    description: 'Average session duration in seconds',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/overview/time-series',
            params={
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-01 00:00:00",
          "sessions": 1250,
          "pageviews": 3890,
          "users": 1100,
          "pages_per_session": 3.11,
          "bounce_rate": 41.5,
          "session_duration": 165.2
        },
        {
          "time": "2024-01-02 00:00:00",
          "sessions": 1420,
          "pageviews": 4520,
          "users": 1280,
          "pages_per_session": 3.18,
          "bounce_rate": 39.8,
          "session_duration": 178.4
        },
        {
          "time": "2024-01-03 00:00:00",
          "sessions": 1380,
          "pageviews": 4210,
          "users": 1190,
          "pages_per_session": 3.05,
          "bounce_rate": 42.1,
          "session_duration": 162.8
        }
      ]
    }
    ```
  </div>
</div>


# Get Performance by Dimension (/docs/api/performance/by-dimension)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/performance/by-dimension
    ```

    Returns performance metrics broken down by a specific dimension (page, country, browser, etc.). Useful for identifying performance issues on specific pages or for specific user segments.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  dimension: {
    description: 'Dimension to break down by',
    type: 'string',
    typeDescription: '&#x22;pathname&#x22; | &#x22;country&#x22; | &#x22;device_type&#x22; | &#x22;browser&#x22; | &#x22;operating_system&#x22; | &#x22;region&#x22;',
    required: true,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    required: false,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  sort_by: {
    description: 'Field to sort by',
    type: 'string',
    default: 'event_count',
  },
  sort_order: {
    description: 'Sort direction',
    type: 'string',
    typeDescription: '&#x22;asc&#x22; | &#x22;desc&#x22;',
    default: 'desc',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Paginated response object',
    type: 'PaginatedResponse',
  },
}"
    />

    #### DimensionPerformance Object [#dimensionperformance-object]

    Each object includes the dimension value plus all percentiles:

    <TypeTable
      type="{
  pathname: {
    description: 'The dimension value (field name matches dimension param)',
    type: 'string',
  },
  event_count: {
    description: 'Number of performance events',
    type: 'number',
  },
  lcp_avg: {
    description: 'Average LCP',
    type: 'number',
  },
  lcp_p50: {
    description: 'LCP 50th percentile',
    type: 'number',
  },
  lcp_p75: {
    description: 'LCP 75th percentile',
    type: 'number',
  },
  lcp_p90: {
    description: 'LCP 90th percentile',
    type: 'number',
  },
  lcp_p99: {
    description: 'LCP 99th percentile',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/performance/by-dimension',
            params={
                'dimension': 'pathname',
                'sort_by': 'lcp_p75',
                'sort_order': 'desc',
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "data": [
          {
            "pathname": "/dashboard",
            "event_count": 12450,
            "lcp_avg": 2850,
            "lcp_p50": 2400,
            "lcp_p75": 3200,
            "lcp_p90": 4100,
            "lcp_p99": 6500,
            "cls_avg": 0.08,
            "cls_p50": 0.05,
            "cls_p75": 0.12,
            "inp_avg": 180,
            "inp_p50": 150,
            "inp_p75": 220,
            "fcp_avg": 1450,
            "fcp_p50": 1300,
            "fcp_p75": 1700,
            "ttfb_avg": 520,
            "ttfb_p50": 480,
            "ttfb_p75": 680
          },
          {
            "pathname": "/reports",
            "event_count": 8920,
            "lcp_avg": 2650,
            "lcp_p50": 2200,
            "lcp_p75": 2900,
            "lcp_p90": 3800,
            "lcp_p99": 5800
          }
        ],
        "totalCount": 156
      }
    }
    ```
  </div>
</div>


# Get Performance Overview (/docs/api/performance/overview)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/performance/overview
    ```

    Returns aggregate performance metrics with percentile breakdowns for all Core Web Vitals.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Performance metrics object',
    type: 'PerformanceMetrics',
  },
}"
    />

    #### PerformanceMetrics Object [#performancemetrics-object]

    Each metric (lcp, cls, inp, fcp, ttfb) includes the following percentiles:

    <TypeTable
      type="{
  lcp_p50: {
    description: 'LCP 50th percentile (median)',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  lcp_p75: {
    description: 'LCP 75th percentile',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  lcp_p90: {
    description: 'LCP 90th percentile',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  lcp_p99: {
    description: 'LCP 99th percentile',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  total_performance_events: {
    description: 'Total number of performance measurements',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/performance/overview',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "lcp_p50": 1850,
        "lcp_p75": 2400,
        "lcp_p90": 3200,
        "lcp_p99": 5100,
        "cls_p50": 0.05,
        "cls_p75": 0.1,
        "cls_p90": 0.18,
        "cls_p99": 0.35,
        "inp_p50": 120,
        "inp_p75": 180,
        "inp_p90": 280,
        "inp_p99": 450,
        "fcp_p50": 1200,
        "fcp_p75": 1600,
        "fcp_p90": 2100,
        "fcp_p99": 3500,
        "ttfb_p50": 450,
        "ttfb_p75": 650,
        "ttfb_p90": 950,
        "ttfb_p99": 1800,
        "total_performance_events": 48521
      }
    }
    ```
  </div>
</div>


# Get Performance Time Series (/docs/api/performance/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/performance/time-series
    ```

    Returns performance metrics over time, broken down by configurable time buckets. Useful for charting performance trends.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data. Defaults to &#x22;hour&#x22; when omitted.',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of time-bucketed performance data',
    type: 'PerformancePoint[]',
  },
}"
    />

    #### PerformancePoint Object [#performancepoint-object]

    Each point includes all percentiles for each metric plus:

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  event_count: {
    description: 'Number of performance events in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/performance/time-series',
            params={
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'UTC'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-01T00:00:00.000Z",
          "lcp_p50": 1820,
          "lcp_p75": 2350,
          "lcp_p90": 3100,
          "lcp_p99": 4900,
          "cls_p50": 0.04,
          "cls_p75": 0.09,
          "inp_p50": 115,
          "inp_p75": 175,
          "fcp_p50": 1180,
          "fcp_p75": 1580,
          "ttfb_p50": 440,
          "ttfb_p75": 640,
          "event_count": 6892
        },
        {
          "time": "2024-01-02T00:00:00.000Z",
          "lcp_p50": 1900,
          "lcp_p75": 2450,
          "lcp_p90": 3250,
          "lcp_p99": 5200,
          "cls_p50": 0.05,
          "cls_p75": 0.11,
          "inp_p50": 125,
          "inp_p75": 185,
          "fcp_p50": 1220,
          "fcp_p75": 1620,
          "ttfb_p50": 460,
          "ttfb_p75": 660,
          "event_count": 7234
        }
      ]
    }
    ```
  </div>
</div>


# Create Segment (/docs/api/segments/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/segments
    ```

    Creates a saved segment. Members create site segments they own; admins and owners can also create organization-wide segments.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Segment name (1–80 characters)',
    type: 'string',
    required: true,
  },
  filters: {
    description: 'Filters that define the segment (1–20). Validated with the same schema as the `filters` parameter',
    type: 'Filter[]',
    typeDescription: 'See Filter Parameters in Getting Started',
    required: true,
  },
  description: {
    description: 'Optional notes (up to 500 characters)',
    type: 'string | null',
    required: false,
  },
  scope: {
    description: 'Where the segment is available. Organization-wide segments require an admin or owner',
    type: 'string',
    typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;',
    default: 'site',
    required: false,
  },
  isPublic: {
    description: 'Show on the public dashboard and private links',
    type: 'boolean',
    default: 'false',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created segment with status 201.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/1/segments" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"name": "Mobile organic from Germany", "filters": [{"parameter": "device_type", "type": "equals", "value": ["Mobile"]}, {"parameter": "channel", "type": "equals", "value": ["Organic Search"]}, {"parameter": "country", "type": "equals", "value": ["DE"]}]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({"name": "Mobile organic from Germany", "filters": [{"parameter": "device_type", "type": "equals", "value": ["Mobile"]}, {"parameter": "channel", "type": "equals", "value": ["Organic Search"]}, {"parameter": "country", "type": "equals", "value": ["DE"]}]})
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/segments',
            json={"name": "Mobile organic from Germany", "filters": [{"parameter": "device_type", "type": "equals", "value": ["Mobile"]}, {"parameter": "channel", "type": "equals", "value": ["Organic Search"]}, {"parameter": "country", "type": "equals", "value": ["DE"]}]},
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "segmentId": 12,
      "siteId": 1,
      "organizationId": "org_abc123",
      "userId": "user_xyz",
      "name": "Mobile organic from Germany",
      "description": null,
      "filters": [
        { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
        { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
        { "parameter": "country", "type": "equals", "value": ["DE"] }
      ],
      "isPublic": false,
      "type": "segment",
      "canEdit": true,
      "createdAt": "2026-09-02T10:15:00.000Z",
      "updatedAt": "2026-09-02T10:15:00.000Z"
    }
    ```
  </div>
</div>


# Delete Segment (/docs/api/segments/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/segments/:segmentId
    ```

    Deletes a saved segment. Admins and owners can delete any segment; members can delete segments they created. Links that already expanded the segment's filters keep working.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  segmentId: {
    description: 'Segment ID',
    type: 'number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the segment was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/1/segments/12" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments/12',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/1/segments/12',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Segment (/docs/api/segments/get)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/segments/:segmentId
    ```

    Returns one saved segment.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  segmentId: {
    description: 'Segment ID',
    type: 'number',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns the segment.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/segments/12" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments/12',
          {
            method: 'GET',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/segments/12',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "segmentId": 12,
      "siteId": 1,
      "organizationId": "org_abc123",
      "userId": "user_xyz",
      "name": "Mobile organic from Germany",
      "description": null,
      "filters": [
        { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
        { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
        { "parameter": "country", "type": "equals", "value": ["DE"] }
      ],
      "isPublic": false,
      "type": "segment",
      "canEdit": true,
      "createdAt": "2026-09-02T10:15:00.000Z",
      "updatedAt": "2026-09-02T10:15:00.000Z"
    }
    ```
  </div>
</div>


# Get Segments (/docs/api/segments/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/segments
    ```

    Returns the saved segments available on a site: its own plus organization-wide ones. Callers without site access only see segments shown on the public dashboard.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns an array of segments, sorted by name.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/segments" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments',
          {
            method: 'GET',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/segments',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    [
      {
        "segmentId": 12,
        "siteId": 1,
        "organizationId": "org_abc123",
        "userId": "user_xyz",
        "name": "Mobile organic from Germany",
        "description": null,
        "filters": [
          { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
          { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
          { "parameter": "country", "type": "equals", "value": ["DE"] }
        ],
        "isPublic": false,
        "type": "segment",
        "canEdit": true,
        "createdAt": "2026-09-02T10:15:00.000Z",
        "updatedAt": "2026-09-02T10:15:00.000Z"
      }
    ]
    ```
  </div>
</div>


# Update Segment (/docs/api/segments/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:site/segments/:segmentId
    ```

    Updates a saved segment. Admins and owners can edit any segment; members can edit segments they created. Only the fields you send change.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  segmentId: {
    description: 'Segment ID',
    type: 'number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Segment name (1–80 characters)',
    type: 'string',
    required: false,
  },
  filters: {
    description: 'Filters that define the segment (1–20). Validated with the same schema as the `filters` parameter',
    type: 'Filter[]',
    typeDescription: 'See Filter Parameters in Getting Started',
    required: false,
  },
  description: {
    description: 'Optional notes (up to 500 characters)',
    type: 'string | null',
    required: false,
  },
  scope: {
    description: 'Where the segment is available. Organization-wide segments require an admin or owner',
    type: 'string',
    typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;',
    default: 'site',
    required: false,
  },
  isPublic: {
    description: 'Show on the public dashboard and private links',
    type: 'boolean',
    default: 'false',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the updated segment.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/sites/1/segments/12" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"name": "Mobile organic (DE)", "isPublic": true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments/12',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({"name": "Mobile organic (DE)", "isPublic": true})
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/sites/1/segments/12',
            json={"name": "Mobile organic (DE)", "isPublic": true},
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "segmentId": 12,
      "siteId": 1,
      "organizationId": "org_abc123",
      "userId": "user_xyz",
      "name": "Mobile organic (DE)",
      "description": null,
      "filters": [
        { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
        { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
        { "parameter": "country", "type": "equals", "value": ["DE"] }
      ],
      "isPublic": true,
      "type": "segment",
      "canEdit": true,
      "createdAt": "2026-09-02T10:15:00.000Z",
      "updatedAt": "2026-09-02T10:15:00.000Z"
    }
    ```
  </div>
</div>


# Delete Session Replay (/docs/api/session-replay/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/session-replay/:sessionId
    ```

    Permanently deletes a session replay recording. Requires site write access.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  sessionId: {
    description: 'The session to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the deletion was successful',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
        req = Net::HTTP::Delete.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Session Replay Events (/docs/api/session-replay/events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/session-replay/:sessionId
    ```

    Returns the rrweb events and metadata needed to reconstruct a session replay.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  sessionId: {
    description: 'The session to fetch',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  events: {
    description: 'Array of rrweb event objects, replayed in order to reconstruct the session. Each carries a timestamp and rrweb-format payload.',
    type: 'RRWebEvent[]',
  },
  metadata: {
    description: &#x22;The session replay metadata object (same fields as a list item, enriched with the user's traits)&#x22;,
    type: 'SessionReplayMetadata',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "events": [
        {
          "type": 4,
          "timestamp": 1705320000000,
          "data": { }
        }
      ],
      "metadata": {
        "session_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "duration_ms": 48200,
        "event_count": 312,
        "browser": "Chrome",
        "...": "..."
      }
    }
    ```
  </div>
</div>


# Get Session Replays (/docs/api/session-replay/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/session-replay/list
    ```

    Returns recorded session replays with metadata, newest first.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters) plus the following:

    <TypeTable
      type="{
  limit: {
    description: 'Number of results to return',
    type: 'number',
    default: 50,
  },
  offset: {
    description: 'Number of results to skip',
    type: 'number',
    default: 0,
  },
  userId: {
    description: 'Restrict to a single user',
    type: 'string',
    required: false,
  },
  minDuration: {
    description: 'Minimum replay duration in seconds',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session replay objects',
    type: 'SessionReplay[]',
  },
}"
    />

    #### SessionReplay Object [#sessionreplay-object]

    Identified users are enriched with their `traits`.

    <TypeTable
      type="{
  session_id: {
    description: 'Unique session identifier',
    type: 'string',
  },
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  start_time: {
    description: 'Replay start time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  end_time: {
    description: 'Replay end time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  duration_ms: {
    description: 'Duration in milliseconds',
    type: 'number',
  },
  page_url: {
    description: 'Entry page',
    type: 'string',
  },
  event_count: {
    description: 'Number of recorded events',
    type: 'number',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/session-replay/list',
            params={
                'limit': 50,
                'offset': 0,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
          "user_id": "dev_xyz789",
          "identified_user_id": "user@example.com",
          "start_time": "2024-01-31T14:00:00.000Z",
          "end_time": "2024-01-31T14:00:48.200Z",
          "duration_ms": 48200,
          "page_url": "/",
          "event_count": 312,
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "browser": "Chrome",
          "browser_version": "120.0.0",
          "operating_system": "macOS",
          "operating_system_version": "14.2",
          "device_type": "desktop",
          "screen_width": 1920,
          "screen_height": 1080
        }
      ]
    }
    ```
  </div>
</div>


# Get Session (/docs/api/sessions/get)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/sessions/:sessionId
    ```

    Returns detailed information about a specific session including all events and pageviews.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  sessionId: {
    description: 'Session ID',
    type: 'string',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  limit: {
    description: 'Number of events to return',
    type: 'number',
    default: 100,
  },
  offset: {
    description: 'Number of events to skip',
    type: 'number',
    default: 0,
  },
  minutes: {
    description: 'Only return events from the last N minutes',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Session details object',
    type: 'SessionDetails',
  },
}"
    />

    #### SessionDetails Object [#sessiondetails-object]

    <TypeTable
      type="{
  session: {
    description: 'Session metadata',
    type: 'SessionMeta',
  },
  events: {
    description: 'Array of events in the session',
    type: 'Event[]',
  },
  pagination: {
    description: 'Pagination info for events',
    type: 'Pagination',
  },
}"
    />

    #### Event Object [#event-object]

    <TypeTable
      type="{
  timestamp: {
    description: 'Event timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
  },
  hostname: {
    description: 'Hostname',
    type: 'string',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;error&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;copy&#x22; | &#x22;form_submit&#x22; | &#x22;input_change&#x22;',
  },
  event_name: {
    description: 'Custom event name (for custom_event type)',
    type: 'string',
  },
  props: {
    description: 'Event properties',
    type: 'object',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/sessions/sess_abc123',
            params={'limit': 50},
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "session": {
          "session_id": "sess_abc123",
          "user_id": "dev_xyz789",
          "country": "US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:04:05.000Z",
          "session_duration": 245,
          "pageviews": 5,
          "events": 7,
          "entry_page": "/",
          "exit_page": "/pricing"
        },
        "events": [
          {
            "timestamp": "2024-01-31T14:00:00.000Z",
            "pathname": "/",
            "hostname": "example.com",
            "page_title": "Home",
            "type": "pageview",
            "referrer": "https://google.com"
          },
          {
            "timestamp": "2024-01-31T14:01:30.000Z",
            "pathname": "/",
            "hostname": "example.com",
            "type": "custom_event",
            "event_name": "cta_click",
            "props": { "button": "hero" }
          }
        ],
        "pagination": {
          "total": 7,
          "limit": 50,
          "offset": 0,
          "hasMore": false
        }
      }
    }
    ```
  </div>
</div>


# Get Sessions (/docs/api/sessions/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/sessions
    ```

    Returns a paginated list of sessions with their analytics data.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  user_id: {
    description: 'Filter sessions by user ID',
    type: 'string',
    required: false,
  },
  identified_only: {
    description: 'Only return sessions from identified users',
    type: 'string',
    typeDescription: '&#x22;true&#x22; | &#x22;false&#x22;',
    default: 'false',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session objects',
    type: 'Session[]',
  },
}"
    />

    #### Session Object [#session-object]

    <TypeTable
      type="{
  session_id: {
    description: 'Unique session identifier',
    type: 'string',
  },
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  traits: {
    description: 'Custom user traits',
    type: 'object | null',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
  },
  channel: {
    description: 'Traffic channel',
    type: 'string',
  },
  entry_page: {
    description: 'First page visited',
    type: 'string',
  },
  exit_page: {
    description: 'Last page visited',
    type: 'string',
  },
  pageviews: {
    description: 'Number of pageviews',
    type: 'number',
  },
  events: {
    description: 'Number of custom events',
    type: 'number',
  },
  session_duration: {
    description: 'Duration in seconds',
    type: 'number',
  },
  session_start: {
    description: 'Session start time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  session_end: {
    description: 'Session end time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  utm_source: {
    description: 'UTM source parameter',
    type: 'string',
  },
  utm_medium: {
    description: 'UTM medium parameter',
    type: 'string',
  },
  utm_campaign: {
    description: 'UTM campaign parameter',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/sessions',
            params={
                'page': 1,
                'limit': 20,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "sess_abc123",
          "user_id": "dev_xyz789",
          "identified_user_id": "user@example.com",
          "traits": { "plan": "pro" },
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "referrer": "https://google.com",
          "channel": "organic",
          "entry_page": "/",
          "exit_page": "/pricing",
          "pageviews": 5,
          "events": 2,
          "session_duration": 245,
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:04:05.000Z",
          "utm_source": "google",
          "utm_medium": "cpc",
          "utm_campaign": "brand"
        }
      ]
    }
    ```
  </div>
</div>


# Get Session Locations (/docs/api/sessions/locations)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/sessions/locations
    ```

    Returns aggregated session locations with coordinates for map visualization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of location objects',
    type: 'Location[]',
  },
}"
    />

    #### Location Object [#location-object]

    <TypeTable
      type="{
  lat: {
    description: 'Latitude coordinate',
    type: 'number',
  },
  lon: {
    description: 'Longitude coordinate',
    type: 'number',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  count: {
    description: 'Number of sessions from this location',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/sessions/locations',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "lat": 37.7749,
          "lon": -122.4194,
          "city": "San Francisco",
          "country": "US",
          "count": 1250
        },
        {
          "lat": 40.7128,
          "lon": -74.006,
          "city": "New York",
          "country": "US",
          "count": 980
        },
        {
          "lat": 51.5074,
          "lon": -0.1278,
          "city": "London",
          "country": "GB",
          "count": 650
        }
      ]
    }
    ```
  </div>
</div>


# Create Team (/docs/api/teams/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/teams
    ```

    Creates a team in an organization. Requires admin/owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Team name',
    type: 'string',
    required: true,
  },
  memberUserIds: {
    description: 'User IDs to add to the team (must be members of the organization)',
    type: 'string[]',
    required: false,
  },
  siteIds: {
    description: 'Site IDs the team can access (must belong to the organization)',
    type: 'number[]',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created team with HTTP 201.

    <TypeTable
      type="{
  id: {
    description: 'Team ID',
    type: 'string',
  },
  name: {
    description: 'Team name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID the team belongs to',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when the team was created',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Timestamp when the team was last updated',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  members: {
    description: 'Array of added user IDs',
    type: 'string[]',
  },
  siteIds: {
    description: 'Array of granted site IDs',
    type: 'number[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_abc123/teams" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"name": "Marketing", "memberUserIds": ["user_123"], "siteIds": [123]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/teams`,
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Marketing',
              memberUserIds: ['user_123'],
              siteIds: [123]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.post(
            f'https://app.rybbit.io/api/organizations/{organization_id}/teams',
            json={
                'name': 'Marketing',
                'memberUserIds': ['user_123'],
                'siteIds': [123]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/teams");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'name' => 'Marketing',
            'memberUserIds' => ['user_123'],
            'siteIds' => [123]
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/teams")
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = {
          name: 'Marketing',
          memberUserIds: ['user_123'],
          siteIds: [123]
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        body := bytes.NewBuffer([]byte(`{
          "name": "Marketing",
          "memberUserIds": ["user_123"],
          "siteIds": [123]
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/"+organizationId+"/teams", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .post(format!("https://app.rybbit.io/api/organizations/{}/teams", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "name": "Marketing",
                "memberUserIds": ["user_123"],
                "siteIds": [123]
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"name\": \"Marketing\", \"memberUserIds\": [\"user_123\"], \"siteIds\": [123]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/teams"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"name\": \"Marketing\", \"memberUserIds\": [\"user_123\"], \"siteIds\": [123]}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"https://app.rybbit.io/api/organizations/{organizationId}/teams", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "team_xyz789",
      "name": "Marketing",
      "organizationId": "org_abc123",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "members": ["user_123"],
      "siteIds": [123]
    }
    ```
  </div>
</div>


# Delete Team (/docs/api/teams/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/organizations/:organizationId/teams/:teamId
    ```

    Deletes a team. Requires admin/owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
  teamId: {
    description: 'ID of the team to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the team was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789')
        request = Net::HTTP::Delete.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Teams (/docs/api/teams/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations/:organizationId/teams
    ```

    Returns the teams in an organization, with their members and accessible sites.

    Any organization member may call this. Members who are not an admin/owner only see the teams they belong to.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  teams: {
    description: 'Array of teams in the organization',
    type: 'array',
  },
}"
    />

    #### Team Object [#team-object]

    Each team in the `teams` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Team ID',
    type: 'string',
  },
  name: {
    description: 'Team name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID the team belongs to',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when the team was created',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Timestamp when the team was last updated',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  members: {
    description: 'Members of the team',
    type: 'array',
  },
  sites: {
    description: 'Sites the team can access',
    type: 'array',
  },
}"
    />

    #### Member Object [#member-object]

    <TypeTable
      type="{
  userId: {
    description: 'User ID',
    type: 'string',
  },
  userName: {
    description: 'User display name',
    type: 'string',
  },
  userEmail: {
    description: 'User email address',
    type: 'string',
  },
}"
    />

    #### Site Object [#site-object]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'number',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations/org_abc123/teams" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/teams`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.get(
            f'https://app.rybbit.io/api/organizations/{organization_id}/teams',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/teams");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/teams")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations/"+organizationId+"/teams", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/organizations/{}/teams", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/teams"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/organizations/{organizationId}/teams");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "teams": [
        {
          "id": "team_xyz789",
          "name": "Marketing",
          "organizationId": "org_abc123",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "updatedAt": "2024-02-20T14:15:00.000Z",
          "members": [
            {
              "userId": "user_123",
              "userName": "John Doe",
              "userEmail": "john@example.com"
            }
          ],
          "sites": [
            {
              "siteId": 123,
              "domain": "example.com",
              "name": "Example Site"
            }
          ]
        }
      ]
    }
    ```
  </div>
</div>


# Update Team (/docs/api/teams/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/organizations/:organizationId/teams/:teamId
    ```

    Updates a team's name, members, or site access. Requires admin/owner role.

    When `memberUserIds` or `siteIds` is provided, it **replaces** the team's entire existing set (it is not merged). Omit a field to leave it unchanged.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
  teamId: {
    description: 'ID of the team to update',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Updated team name',
    type: 'string',
    required: false,
  },
  memberUserIds: {
    description: 'User IDs to set as the team members (replaces the existing set)',
    type: 'string[]',
    required: false,
  },
  siteIds: {
    description: 'Site IDs to set as the team site access (replaces the existing set)',
    type: 'number[]',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the team was updated',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Growth",
            "memberUserIds": ["user_123", "user_456"]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Growth',
              memberUserIds: ['user_123', 'user_456']
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
            json={
                'name': 'Growth',
                'memberUserIds': ['user_123', 'user_456']
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Growth',
            'memberUserIds' => ['user_123', 'user_456']
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789')
        request = Net::HTTP::Put.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Growth',
          memberUserIds: ['user_123', 'user_456']
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Growth",
            "memberUserIds": []string{"user_123", "user_456"},
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("PUT", "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Growth",
            "memberUserIds": ["user_123", "user_456"]
        });

        let client = reqwest::Client::new();
        let res = client
            .put("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Growth",
          "memberUserIds": ["user_123", "user_456"]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Growth",
            memberUserIds = new[] { "user_123", "user_456" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PutAsync("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Delete Site (/docs/api/sites/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:siteId
    ```

    Permanently deletes a site and all its associated data. This action cannot be undone. Requires admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the deletion was successful',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123')
        req = Net::HTTP::Delete.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Excluded Countries (/docs/api/sites/excluded-countries)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId/excluded-countries
    ```

    Returns the list of country codes that are excluded from tracking.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedCountries: {
    description: 'Array of excluded country codes (2-letter ISO codes)',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-countries" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-countries',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-countries',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-countries');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-countries')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-countries", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-countries")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-countries"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-countries");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedCountries": [
        "CN",
        "RU",
        "KP"
      ]
    }
    ```
  </div>
</div>


# Get Excluded Hostnames (/docs/api/sites/excluded-hostnames)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/excluded-hostnames
    ```

    Returns the list of hostnames excluded from analytics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedHostnames: {
    description: 'Array of excluded hostnames',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-hostnames" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-hostnames',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-hostnames',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-hostnames');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-hostnames')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-hostnames", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-hostnames")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-hostnames"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-hostnames");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedHostnames": [
        "staging.example.com"
      ]
    }
    ```
  </div>
</div>


# Get Excluded IPs (/docs/api/sites/excluded-ips)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId/excluded-ips
    ```

    Returns the list of IP addresses and CIDR ranges that are excluded from tracking.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedIPs: {
    description: 'Array of excluded IP addresses or CIDR ranges',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-ips" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-ips',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-ips',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-ips');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-ips')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-ips", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-ips")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-ips"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-ips");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedIPs": [
        "192.168.1.1",
        "10.0.0.0/8",
        "172.16.0.0/12"
      ]
    }
    ```
  </div>
</div>


# Get Excluded Paths (/docs/api/sites/excluded-paths)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/excluded-paths
    ```

    Returns the list of URL paths excluded from analytics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedPaths: {
    description: 'Array of excluded URL paths',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-paths" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-paths',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-paths',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-paths');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-paths')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-paths", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-paths")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-paths"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-paths");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedPaths": [
        "/admin",
        "/internal/*"
      ]
    }
    ```
  </div>
</div>


# Get Excluded User Agents (/docs/api/sites/excluded-user-agents)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/excluded-user-agents
    ```

    Returns the list of user-agent patterns excluded from analytics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedUserAgents: {
    description: 'Array of excluded user-agent patterns',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-user-agents" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-user-agents',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-user-agents',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-user-agents');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-user-agents')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-user-agents", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-user-agents")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-user-agents"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-user-agents");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedUserAgents": [
        "*HeadlessChrome*"
      ]
    }
    ```
  </div>
</div>


# Export PDF Report (/docs/api/sites/export-pdf)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/export/pdf
    ```

    Generates a downloadable PDF analytics report for a date range.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  start_date: {
    description: 'Start of the date range',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
    required: true,
  },
  end_date: {
    description: 'End of the date range',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
    required: true,
  },
  time_zone: {
    description: 'IANA timezone',
    type: 'string',
    required: true,
  },
  filters: {
    description: 'JSON-encoded filter array (same format as the Common Parameters filters)',
    type: 'string',
  },
}"
    />

    ### Response [#response]

    Returns a binary PDF file (`Content-Type: application/pdf`). Save the response body to a `.pdf` file rather than parsing it as JSON.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here" \
          -o report.pdf
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const blob = await response.blob();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/export/pdf',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        with open('report.pdf', 'wb') as f:
            f.write(response.content)
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        file_put_contents('report.pdf', $response);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'

        uri = URI('https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        File.binwrite('report.pdf', res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        out, _ := os.Create("report.pdf")
        defer out.Close()
        io.Copy(out, resp.Body)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let bytes = res.bytes().await?;
        std::fs::write("report.pdf", &bytes)?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<Path> response = client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("report.pdf")));
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var bytes = await response.Content.ReadAsByteArrayAsync();
        File.WriteAllBytes("report.pdf", bytes);
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Get Private Link Config (/docs/api/sites/get-private-link)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId/private-link-config
    ```

    Returns the private link key configuration. Private links allow sharing analytics with a secret key without requiring authentication.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  data: {
    description: 'Private link configuration',
    type: 'object',
  },
}"
    />

    #### Data Object [#data-object]

    <TypeTable
      type="{
  privateLinkKey: {
    description: 'Private link key, or null if not generated',
    type: 'string | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/private-link-config" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/private-link-config',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/private-link-config',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/private-link-config');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/private-link-config')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/private-link-config", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/private-link-config")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/private-link-config"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/private-link-config");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": {
        "privateLinkKey": "a1b2c3d4e5f6"
      }
    }
    ```
  </div>
</div>


# Get Site (/docs/api/sites/get)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId
    ```

    Returns detailed information about a specific site including its configuration.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  id: {
    description: 'Site UUID',
    type: 'string | null',
  },
  siteId: {
    description: 'Numeric site ID',
    type: 'number',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  createdBy: {
    description: 'User ID who created the site',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string | null',
  },
  public: {
    description: 'Whether the site analytics are publicly accessible',
    type: 'boolean',
  },
  saltUserIds: {
    description: 'Whether user IDs are salted for privacy',
    type: 'boolean',
  },
  blockBots: {
    description: 'Whether bot traffic is blocked',
    type: 'boolean',
  },
  isOwner: {
    description: 'Whether the current user owns this site',
    type: 'boolean',
  },
  sessionReplay: {
    description: 'Whether session replay is enabled',
    type: 'boolean',
  },
  webVitals: {
    description: 'Whether Web Vitals tracking is enabled',
    type: 'boolean',
  },
  trackErrors: {
    description: 'Whether error tracking is enabled',
    type: 'boolean',
  },
  trackOutbound: {
    description: 'Whether outbound link tracking is enabled',
    type: 'boolean',
  },
  trackUrlParams: {
    description: 'Whether URL parameter tracking is enabled',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "site_abc123",
      "siteId": 123,
      "name": "My Website",
      "domain": "example.com",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-31T14:00:00.000Z",
      "createdBy": "user_xyz789",
      "organizationId": "org_def456",
      "public": false,
      "saltUserIds": false,
      "blockBots": true,
      "isOwner": true,
      "sessionReplay": true,
      "webVitals": true,
      "trackErrors": true,
      "trackOutbound": true,
      "trackUrlParams": false
    }
    ```
  </div>
</div>


# Get Site Has Data (/docs/api/sites/has-data)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/has-data
    ```

    Returns whether the site has received any analytics events.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  hasData: {
    description: 'Whether the site has received any analytics events',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/has-data" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/has-data',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/has-data',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/has-data');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/has-data')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/has-data", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/has-data")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/has-data"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/has-data");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "hasData": true
    }
    ```
  </div>
</div>


# Get Site Public Status (/docs/api/sites/is-public)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/is-public
    ```

    Returns whether the site's analytics are publicly accessible.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  isPublic: {
    description: &#x22;Whether the site's analytics are publicly accessible&#x22;,
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/is-public" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/is-public',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/is-public',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/is-public');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/is-public')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/is-public", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/is-public")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/is-public"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/is-public");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "isPublic": false
    }
    ```
  </div>
</div>


# Update Site Config (/docs/api/sites/update-config)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:siteId/config
    ```

    Updates site configuration settings. All fields are optional - only include the fields you want to update. Requires admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  domain: {
    description: 'Site domain',
    type: 'string',
    typeDescription: 'Valid domain format (e.g., example.com)',
    required: false,
  },
  public: {
    description: 'Make analytics publicly accessible',
    type: 'boolean',
    required: false,
  },
  saltUserIds: {
    description: 'Salt user IDs for privacy',
    type: 'boolean',
    required: false,
  },
  blockBots: {
    description: 'Block bot traffic',
    type: 'boolean',
    required: false,
  },
  excludedIPs: {
    description: 'List of IP addresses or CIDR ranges to exclude',
    type: 'string[]',
    typeDescription: 'Max 100 entries',
    required: false,
  },
  excludedCountries: {
    description: 'List of country codes to exclude',
    type: 'string[]',
    typeDescription: '2-letter ISO codes (e.g., US, GB)',
    required: false,
  },
  sessionReplay: {
    description: 'Enable session replay',
    type: 'boolean',
    required: false,
  },
  webVitals: {
    description: 'Enable Web Vitals tracking',
    type: 'boolean',
    required: false,
  },
  trackErrors: {
    description: 'Enable error tracking',
    type: 'boolean',
    required: false,
  },
  trackOutbound: {
    description: 'Enable outbound link tracking',
    type: 'boolean',
    required: false,
  },
  trackUrlParams: {
    description: 'Enable URL parameter tracking',
    type: 'boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the update was successful',
    type: 'boolean',
  },
  message: {
    description: 'Status message',
    type: 'string',
  },
  config: {
    description: 'Updated site configuration',
    type: 'object',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/sites/123/config" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"public": true, "blockBots": true, "excludedCountries": ["CN", "RU"]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/config',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              public: true,
              blockBots: true,
              excludedCountries: ['CN', 'RU']
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/sites/123/config',
            json={
                'public': True,
                'blockBots': True,
                'excludedCountries': ['CN', 'RU']
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/config');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'public' => true,
            'blockBots' => true,
            'excludedCountries' => ['CN', 'RU']
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/config')
        req = Net::HTTP::Put.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = { public: true, blockBots: true, excludedCountries: ['CN', 'RU'] }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{"public": true, "blockBots": true, "excludedCountries": ["CN", "RU"]}`))
        req, _ := http.NewRequest("PUT", "https://app.rybbit.io/api/sites/123/config", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .put("https://app.rybbit.io/api/sites/123/config")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "public": true,
                "blockBots": true,
                "excludedCountries": ["CN", "RU"]
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"public\": true, \"blockBots\": true, \"excludedCountries\": [\"CN\", \"RU\"]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/config"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"public\": true, \"blockBots\": true, \"excludedCountries\": [\"CN\", \"RU\"]}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PutAsync("https://app.rybbit.io/api/sites/123/config", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "message": "Site configuration updated successfully",
      "config": {
        "public": true,
        "saltUserIds": false,
        "blockBots": true,
        "excludedIPs": [],
        "excludedCountries": ["CN", "RU"],
        "sessionReplay": true,
        "webVitals": true,
        "trackErrors": true,
        "trackOutbound": true,
        "trackUrlParams": false
      }
    }
    ```
  </div>
</div>


# Update Private Link Config (/docs/api/sites/update-private-link)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:siteId/private-link-config
    ```

    Generates or revokes a private link key for sharing analytics without authentication. Requires admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  action: {
    description: 'Action to perform',
    type: 'string',
    typeDescription: '&#x22;generate_private_link_key&#x22; | &#x22;revoke_private_link_key&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  data: {
    description: 'Updated private link configuration',
    type: 'object',
  },
}"
    />

    #### Data Object [#data-object]

    <TypeTable
      type="{
  privateLinkKey: {
    description: 'New private link key (for generate), or null (for revoke)',
    type: 'string | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/123/private-link-config" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"action": "generate_private_link_key"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/private-link-config',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              action: 'generate_private_link_key'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/123/private-link-config',
            json={
                'action': 'generate_private_link_key'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/private-link-config');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'action' => 'generate_private_link_key'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/private-link-config')
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = { action: 'generate_private_link_key' }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{"action": "generate_private_link_key"}`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/123/private-link-config", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/123/private-link-config")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "action": "generate_private_link_key"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"action\": \"generate_private_link_key\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/private-link-config"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"action\": \"generate_private_link_key\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/123/private-link-config", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": {
        "privateLinkKey": "f6e5d4c3b2a1"
      }
    }
    ```
  </div>
</div>


# Get User Trait Keys (/docs/api/user-traits/keys)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/user-traits/keys
    ```

    Returns the known user trait keys with the number of users that have each.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  keys: {
    description: 'Array of user trait keys',
    type: 'TraitKey[]',
  },
}"
    />

    #### TraitKey Object [#traitkey-object]

    <TypeTable
      type="{
  key: {
    description: 'The trait name',
    type: 'string',
  },
  userCount: {
    description: 'Number of users that have this trait',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/user-traits/keys" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/user-traits/keys',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/user-traits/keys',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/user-traits/keys');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/user-traits/keys')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/user-traits/keys", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/user-traits/keys")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/user-traits/keys"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/user-traits/keys");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "keys": [
        { "key": "plan", "userCount": 1240 },
        { "key": "company", "userCount": 860 }
      ]
    }
    ```
  </div>
</div>


# Get Users by Trait (/docs/api/user-traits/users)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/user-traits/users
    ```

    Returns users matching a specific trait key and value, with location and session metadata.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  key: {
    description: 'The trait key to match on',
    type: 'string',
    required: true,
  },
  value: {
    description: 'The trait value to match on',
    type: 'string',
    required: true,
  },
  limit: {
    description: 'Maximum number of users to return',
    type: 'number',
    default: '50',
  },
  offset: {
    description: 'Number of users to skip',
    type: 'number',
    default: '0',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  users: {
    description: 'Array of matching users',
    type: 'TraitUser[]',
  },
  total: {
    description: 'Total number of matching users',
    type: 'number',
  },
  hasMore: {
    description: 'Whether more users are available beyond this page',
    type: 'boolean',
  },
}"
    />

    #### TraitUser Object [#traituser-object]

    <TypeTable
      type="{
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  traits: {
    description: &#x22;The user's full traits map&#x22;,
    type: 'object',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  sessions: {
    description: 'Total number of sessions',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/user-traits/users',
            params={
                'key': 'plan',
                'value': 'pro'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "users": [
        {
          "user_id": "a1b2c3",
          "identified_user_id": "user_987",
          "traits": { "plan": "pro", "company": "Acme" },
          "country": "US",
          "region": "California",
          "city": "CA-San Francisco",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "sessions": 14
        }
      ],
      "total": 1,
      "hasMore": false
    }
    ```
  </div>
</div>


# Get User Trait Values (/docs/api/user-traits/values)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/user-traits/values
    ```

    Returns the distinct values for a given trait key, with user counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  key: {
    description: 'The trait key to list values for',
    type: 'string',
    required: true,
  },
  limit: {
    description: 'Maximum number of values to return',
    type: 'number',
    default: '1000',
  },
  offset: {
    description: 'Number of values to skip',
    type: 'number',
    default: '0',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  values: {
    description: 'Array of distinct trait values',
    type: 'TraitValue[]',
  },
  total: {
    description: 'Total number of distinct values',
    type: 'number',
  },
  hasMore: {
    description: 'Whether more values are available beyond this page',
    type: 'boolean',
  },
}"
    />

    #### TraitValue Object [#traitvalue-object]

    <TypeTable
      type="{
  value: {
    description: 'The trait value',
    type: 'string',
  },
  userCount: {
    description: 'Number of users with this value',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/user-traits/values?key=plan" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/user-traits/values?key=plan',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/user-traits/values',
            params={
                'key': 'plan'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/user-traits/values?key=plan');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/user-traits/values?key=plan')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/user-traits/values?key=plan", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/user-traits/values?key=plan")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/user-traits/values?key=plan"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/user-traits/values?key=plan");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "values": [
        { "value": "pro", "userCount": 340 },
        { "value": "free", "userCount": 900 }
      ],
      "total": 2,
      "hasMore": false
    }
    ```
  </div>
</div>


# Get User Info (/docs/api/users/info)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/users/:userId
    ```

    Returns detailed information about a specific user, including their profile traits and linked devices.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  userId: {
    description: 'User ID (device fingerprint or identified user ID)',
    type: 'string',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'User info object',
    type: 'UserInfo',
  },
}"
    />

    #### UserInfo Object [#userinfo-object]

    <TypeTable
      type="{
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  traits: {
    description: 'Custom user traits/properties set via identify()',
    type: 'object | null',
  },
  sessions: {
    description: 'Total number of sessions',
    type: 'number',
  },
  pageviews: {
    description: 'Total pageviews',
    type: 'number',
  },
  events: {
    description: 'Total custom events',
    type: 'number',
  },
  duration: {
    description: 'Average session duration in seconds',
    type: 'number',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  language: {
    description: 'Browser language',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
  first_seen: {
    description: 'First activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  last_seen: {
    description: 'Most recent activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  timezone: {
    description: 'Timezone reported by the browser',
    type: 'string',
  },
  ip: {
    description: 'Last known IP address',
    type: 'string',
  },
  first_referrer: {
    description: 'Referrer URL of the first session',
    type: 'string',
  },
  first_channel: {
    description: 'Acquisition channel of the first session',
    type: 'string',
  },
  first_entry_page: {
    description: 'Entry page path of the first session',
    type: 'string',
  },
  first_utm_source: {
    description: 'UTM source of the first session',
    type: 'string',
  },
  first_utm_medium: {
    description: 'UTM medium of the first session',
    type: 'string',
  },
  first_utm_campaign: {
    description: 'UTM campaign of the first session',
    type: 'string',
  },
  last_referrer: {
    description: 'Referrer URL of the most recent session',
    type: 'string',
  },
  last_channel: {
    description: 'Acquisition channel of the most recent session',
    type: 'string',
  },
  vitals: {
    description: 'p75 Core Web Vitals for this user, or null when no performance data exists',
    type: 'UserVitals | null',
  },
  locations: {
    description: 'Per-location breakdown of sessions',
    type: 'UserLocation[]',
  },
  devices: {
    description: 'Per-device breakdown of sessions',
    type: 'UserDevice[]',
  },
  linked_devices: {
    description: 'Devices linked to this identified user',
    type: 'LinkedDevice[]',
  },
}"
    />

    #### UserVitals Object [#uservitals-object]

    <TypeTable
      type="{
  lcp_p75: {
    description: 'p75 Largest Contentful Paint (ms)',
    type: 'number | null',
  },
  cls_p75: {
    description: 'p75 Cumulative Layout Shift',
    type: 'number | null',
  },
  inp_p75: {
    description: 'p75 Interaction to Next Paint (ms)',
    type: 'number | null',
  },
  fcp_p75: {
    description: 'p75 First Contentful Paint (ms)',
    type: 'number | null',
  },
  ttfb_p75: {
    description: 'p75 Time to First Byte (ms)',
    type: 'number | null',
  },
  performance_events: {
    description: 'Number of performance events collected',
    type: 'number',
  },
}"
    />

    #### UserLocation Object [#userlocation-object]

    <TypeTable
      type="{
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  sessions: {
    description: 'Number of sessions from this location',
    type: 'number',
  },
  last_seen: {
    description: 'Most recent activity from this location',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />

    #### UserDevice Object [#userdevice-object]

    <TypeTable
      type="{
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
  sessions: {
    description: 'Number of sessions on this device',
    type: 'number',
  },
  last_seen: {
    description: 'Most recent activity on this device',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />

    #### LinkedDevice Object [#linkeddevice-object]

    <TypeTable
      type="{
  anonymous_id: {
    description: 'Anonymous device fingerprint',
    type: 'string',
  },
  created_at: {
    description: 'When the device was linked',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/users/user@example.com" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/users/user@example.com',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/users/user@example.com',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/users/user@example.com');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/users/user@example.com')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/users/user@example.com", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/users/user@example.com")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/users/user@example.com"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/users/user@example.com");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "user_id": "abc123def456",
        "identified_user_id": "user@example.com",
        "traits": {
          "name": "John Doe",
          "plan": "pro",
          "company": "Acme Inc"
        },
        "sessions": 12,
        "pageviews": 156,
        "events": 23,
        "duration": 245,
        "country": "US",
        "region": "California",
        "city": "San Francisco",
        "language": "en-US",
        "browser": "Chrome",
        "browser_version": "120.0.0",
        "operating_system": "macOS",
        "operating_system_version": "14.2",
        "device_type": "desktop",
        "screen_width": 2560,
        "screen_height": 1440,
        "first_seen": "2024-01-15T10:30:00.000Z",
        "last_seen": "2024-01-31T14:22:00.000Z",
        "timezone": "America/Los_Angeles",
        "ip": "203.0.113.42",
        "first_referrer": "https://google.com",
        "first_channel": "Organic Search",
        "first_entry_page": "/pricing",
        "first_utm_source": "google",
        "first_utm_medium": "cpc",
        "first_utm_campaign": "launch",
        "last_referrer": "https://twitter.com",
        "last_channel": "Social",
        "vitals": {
          "lcp_p75": 1240,
          "cls_p75": 0.02,
          "inp_p75": 180,
          "fcp_p75": 890,
          "ttfb_p75": 210,
          "performance_events": 48
        },
        "locations": [
          {
            "country": "US",
            "region": "California",
            "city": "San Francisco",
            "sessions": 10,
            "last_seen": "2024-01-31T14:22:00.000Z"
          }
        ],
        "devices": [
          {
            "device_type": "desktop",
            "browser": "Chrome",
            "browser_version": "120.0.0",
            "operating_system": "macOS",
            "operating_system_version": "14.2",
            "screen_width": 2560,
            "screen_height": 1440,
            "sessions": 9,
            "last_seen": "2024-01-31T14:22:00.000Z"
          }
        ],
        "linked_devices": [
          {
            "anonymous_id": "xyz789ghi012",
            "created_at": "2024-01-20T08:15:00.000Z"
          }
        ]
      }
    }
    ```
  </div>
</div>


# Get Users (/docs/api/users/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/users
    ```

    Returns a paginated list of users with their analytics data. Supports filtering by identified users only.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  page_size: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  sort_by: {
    description: 'Field to sort by',
    type: 'string',
    typeDescription: '&#x22;first_seen&#x22; | &#x22;last_seen&#x22; | &#x22;pageviews&#x22; | &#x22;sessions&#x22; | &#x22;events&#x22;',
    default: 'last_seen',
  },
  sort_order: {
    description: 'Sort direction',
    type: 'string',
    typeDescription: '&#x22;asc&#x22; | &#x22;desc&#x22;',
    default: 'desc',
  },
  identified_only: {
    description: 'Only return users with a custom identified_user_id',
    type: 'string',
    typeDescription: '&#x22;true&#x22; | &#x22;false&#x22;',
    default: 'false',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of user objects',
    type: 'User[]',
  },
  totalCount: {
    description: 'Total number of users across all pages',
    type: 'number',
  },
  page: {
    description: 'Current page number',
    type: 'number',
  },
  pageSize: {
    description: 'Number of results per page',
    type: 'number',
  },
}"
    />

    #### User Object [#user-object]

    <TypeTable
      type="{
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified, empty string otherwise',
    type: 'string',
  },
  traits: {
    description: 'Custom user traits/properties',
    type: 'object | null',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  language: {
    description: 'Browser language',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  device_type: {
    description: 'Device type (desktop, mobile, tablet)',
    type: 'string',
  },
  pageviews: {
    description: 'Total pageviews by this user',
    type: 'number',
  },
  events: {
    description: 'Total custom events by this user',
    type: 'number',
  },
  sessions: {
    description: 'Total sessions by this user',
    type: 'number',
  },
  hostname: {
    description: 'First hostname visited',
    type: 'string',
  },
  first_seen: {
    description: 'First activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  last_seen: {
    description: 'Most recent activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/users',
            params={
                'page': 1,
                'page_size': 10,
                'sort_by': 'last_seen',
                'sort_order': 'desc'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "user_id": "abc123def456",
          "identified_user_id": "user@example.com",
          "traits": {
            "plan": "pro",
            "company": "Acme Inc"
          },
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "language": "en-US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "pageviews": 156,
          "events": 23,
          "sessions": 12,
          "hostname": "example.com",
          "first_seen": "2024-01-15T10:30:00.000Z",
          "last_seen": "2024-01-31T14:22:00.000Z"
        }
      ],
      "totalCount": 1247,
      "page": 1,
      "pageSize": 10
    }
    ```
  </div>
</div>


# Get User Session Count (/docs/api/users/session-count)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/users/session-count
    ```

    Returns the number of sessions per day for a specific user. Useful for visualizing user engagement over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  user_id: {
    description: 'User ID (device fingerprint or identified user ID)',
    type: 'string',
    required: true,
  },
  time_zone: {
    description: 'Timezone for date grouping',
    type: 'string',
    default: 'UTC',
    typeDescription: 'IANA timezone (e.g., &#x22;America/New_York&#x22;)',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of daily session counts',
    type: 'DailyCount[]',
  },
}"
    />

    #### DailyCount Object [#dailycount-object]

    <TypeTable
      type="{
  date: {
    description: 'Date',
    type: 'string',
    typeDescription: 'YYYY-MM-DD format',
  },
  sessions: {
    description: 'Number of sessions on this date',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/users/session-count',
            params={
                'user_id': 'abc123def456',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "date": "2024-01-15",
          "sessions": 2
        },
        {
          "date": "2024-01-18",
          "sessions": 1
        },
        {
          "date": "2024-01-22",
          "sessions": 3
        },
        {
          "date": "2024-01-31",
          "sessions": 1
        }
      ]
    }
    ```
  </div>
</div>


# Gatsby (/docs/guides/react/gatsby)





Gatsby generates the `<head>` of every page at build time. Add the snippet through the `onRenderBody` API in `gatsby-ssr.js`, or with Gatsby's own `<Script>` component if you want control over load timing.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Gatsby [#add-the-snippet-to-gatsby]

    <Tabs items="[&#x22;gatsby-ssr.js&#x22;, &#x22;Gatsby Script component&#x22;]">
      <Tab value="gatsby-ssr.js">
        Create `gatsby-ssr.js` at the root of your project if it does not exist and register the script with `setHeadComponents`:

        ```javascript title="gatsby-ssr.js"
        import React from "react";

        export const onRenderBody = ({ setHeadComponents }) => {
          setHeadComponents([
            <script
              key="rybbit-analytics"
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              defer
            />,
          ]);
        };
        ```

        This puts the tag in the `<head>` of every generated page.
      </Tab>

      <Tab value="Gatsby Script component">
        The [Gatsby Script API](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-script/) loads third-party scripts with a chosen `strategy` (`post-hydrate`, `idle` or `off-main-thread`). Render it in a layout component that wraps every page:

        ```jsx title="src/components/layout.js"
        import React from "react";
        import { Script } from "gatsby";

        export default function Layout({ children }) {
          return (
            <>
              {children}
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="post-hydrate"
              />
            </>
          );
        }
        ```
      </Tab>
    </Tabs>

    Rebuild the site (`gatsby build`) and deploy the `public` folder. Client-side navigation through Gatsby's `<Link>` is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any React component. Guard the call, because Gatsby renders components on the server during the build.

```jsx title="src/components/TrackedButton.js"
import React from "react";

export default function TrackedButton({ label, eventName, eventData }) {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event(eventName, eventData);
    }
  };

  return <button onClick={handleClick}>{label}</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after client-side navigation**: this is rare. If it happens, export `onRouteUpdate` from `gatsby-browser.js` and call `window.rybbit.pageview()` there when `location.pathname` changes. Test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Next.js (/docs/guides/react/next-js)





Next.js ships a [Script component](https://nextjs.org/docs/app/building-your-application/optimizing/scripts) that controls when a third-party script loads. Render it once in your root layout (App Router) or custom `App` (Pages Router) so the snippet is on every page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Next.js [#add-the-snippet-to-nextjs]

    Use `next/script` with `strategy="afterInteractive"` instead of a plain `<script>` tag. The `defer` attribute from the snippet is not needed; the strategy handles load timing.

    <Tabs items="[&#x22;App Router&#x22;, &#x22;Pages Router&#x22;]">
      <Tab value="App Router">
        ```jsx title="app/layout.js"
        import Script from "next/script";

        export default function RootLayout({ children }) {
          return (
            <html lang="en">
              <body>
                {children}
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```
      </Tab>

      <Tab value="Pages Router">
        ```jsx title="pages/_app.js"
        import Script from "next/script";

        export default function MyApp({ Component, pageProps }) {
          return (
            <>
              <Component {...pageProps} />
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </>
          );
        }
        ```
      </Tab>
    </Tabs>

    Client-side navigation through `<Link>` and `router.push()` is tracked automatically as pageviews; no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any client component. Guard the call, because the script loads after hydration and components can also render on the server.

```jsx title="components/MyButton.js"
"use client";

export default function MyButton({ title }) {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("button_click", { buttonTitle: title });
    }
  };

  return <button onClick={handleClick}>{title}</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Proxying through your own domain**: Next.js [rewrites](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites) can serve the script and its API from your domain. Follow the [Next.js proxy guide](/docs/proxy-guide/next-js); every endpoint must be rewritten, including `site/tracking-config`, otherwise the script silently falls back to default settings and features such as web vitals and session replay stay off.
* **Pageviews missing after client-side navigation**: this is rare; call `window.rybbit.pageview()` yourself after the route change only if the default behaviour does not work for you.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# React Router (/docs/guides/react/react-router)





In React Router framework mode (v7 and later, the successor to Remix), `app/root.tsx` renders the `<html>` document for every route. Add the snippet to the `<head>` in its `Layout` export. This guide supersedes the [Remix guide](/docs/guides/react/remix); if you use React Router only as a library inside a Vite app, follow the [React (Vite / CRA) guide](/docs/guides/react/vite-cra) instead.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to React Router [#add-the-snippet-to-react-router]

    Open `app/root.tsx` and add the tag inside `<head>` of the `Layout` component, after `<Meta />` and `<Links />`. `Layout` wraps the app, `HydrateFallback` and `ErrorBoundary`, so the snippet stays in place in every state:

    ```tsx title="app/root.tsx"
    import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";

    export function Layout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <Meta />
            <Links />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            {children}
            <ScrollRestoration />
            <Scripts />
          </body>
        </html>
      );
    }

    export default function App() {
      return <Outlet />;
    }
    ```

    If your `root.tsx` has no `Layout` export, add the tag to the `<head>` of the default `App` component instead. Restart the dev server after the change. Client-side navigation through `<Link>` and `useNavigate()` is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any route or component. Check for `window` first, because route modules also render on the server.

```tsx title="app/routes/pricing.tsx"
export default function Pricing() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("plan_selected", { plan: "pro" });
    }
  };

  return <button onClick={handleClick}>Choose Pro</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Nonce-based Content Security Policy**: if you pass a `nonce` to `<Scripts />` and `<ScrollRestoration />`, add the same `nonce` attribute to the Rybbit tag, otherwise the browser blocks it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Remix (/docs/guides/react/remix)





Remix renders the whole HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file and reaches every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Remix [#add-the-snippet-to-remix]

    Open `app/root.tsx` (or `app/root.jsx`) and add the tag inside `<head>`, after `<Meta />` and `<Links />`:

    ```tsx title="app/root.tsx"
    import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "@remix-run/react";

    export default function App() {
      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <Meta />
            <Links />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            <Outlet />
            <ScrollRestoration />
            <Scripts />
          </body>
        </html>
      );
    }
    ```

    Restart the dev server after the change. Client-side navigation after the initial server render is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any route or component. Check for `window` first, because Remix renders components on the server.

```tsx title="app/routes/offer.tsx"
export default function OfferRoute() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("offer_claimed", { feature: "Special Offer" });
    }
  };

  return <button onClick={handleClick}>Claim Offer</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after client-side navigation**: this is rare. If it happens, call `window.rybbit.pageview()` from a root-level effect that runs on `useLocation()` changes; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# TanStack Start (/docs/guides/react/tanstack-start)





TanStack Start manages the document head through the root route's `head()` option, rendered by `<HeadContent />` in `src/routes/__root.tsx`. Add the snippet to the `scripts` array returned by `head()` and it is on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to TanStack Start [#add-the-snippet-to-tanstack-start]

    Open `src/routes/__root.tsx` and add a `scripts` entry to the object returned by `head()`. `<HeadContent />` in the root document renders it as a `<script>` tag inside `<head>`:

    ```tsx title="src/routes/__root.tsx"
    import type { ReactNode } from "react";
    import { Outlet, createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";

    export const Route = createRootRoute({
      head: () => ({
        meta: [
          { charSet: "utf-8" },
          { name: "viewport", content: "width=device-width, initial-scale=1" },
          { title: "My App" },
        ],
        scripts: [
          {
            src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
            defer: true,
          },
        ],
      }),
      component: RootComponent,
    });

    function RootComponent() {
      return (
        <RootDocument>
          <Outlet />
        </RootDocument>
      );
    }

    function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
      return (
        <html>
          <head>
            <HeadContent />
          </head>
          <body>
            {children}
            <Scripts />
          </body>
        </html>
      );
    }
    ```

    Use the `scripts` key inside `head()`, not the route-level `scripts` option: that one renders body scripts through `<Scripts />`, which also works but loads later. Client-side navigation through `<Link>` and `useNavigate()` is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any route component. Check for `window` first, because TanStack Start renders routes on the server by default.

```tsx title="src/routes/pricing.tsx"
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/pricing")({
  component: Pricing,
});

function Pricing() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("plan_selected", { plan: "pro" });
    }
  };

  return <button onClick={handleClick}>Choose Pro</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# React (Vite / CRA) (/docs/guides/react/vite-cra)





A client-side React app built with Vite or Create React App has a single HTML entry file. Paste the snippet into its `<head>` and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to React [#add-the-snippet-to-react]

    Find the HTML entry file for your tooling:

    * **Vite**: `index.html` at the project root.
    * **Create React App**: `public/index.html`.

    Paste the snippet just before `</head>`:

    ```html title="index.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <title>My React App</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="root"></div>
      </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Route changes made by React Router and similar libraries are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw.

```jsx title="src/components/LearnMoreButton.jsx"
export default function LearnMoreButton() {
  const handleClick = () => {
    if (window.rybbit) {
      window.rybbit.event("button_click", { category: "CTA", label: "Learn More" });
    }
  };

  return <button onClick={handleClick}>Learn More</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: this is rare with React Router. If it happens, call `window.rybbit.pageview()` after each route change; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# SvelteKit (/docs/guides/svelte/sveltekit)





SvelteKit renders every page through a single HTML shell at `src/app.html`, so adding the snippet there loads Rybbit on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to SvelteKit [#add-the-snippet-to-sveltekit]

    Open `src/app.html` and paste the snippet inside `<head>`, next to `%sveltekit.head%`:

    ```html title="src/app.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <link rel="icon" href="%sveltekit.assets%/favicon.png" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        %sveltekit.head%
      </head>
      <body data-sveltekit-preload-data="hover">
        <div style="display: contents">%sveltekit.body%</div>
      </body>
    </html>
    ```

    Rybbit tracks SvelteKit's client-side navigations as pageviews automatically; no router hook is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any Svelte component. Guard the call with `typeof window !== "undefined"`, since SvelteKit components also run on the server:

```svelte title="src/lib/components/ActionButton.svelte"
<script>
  function handleAction() {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("user_action", { component: "ActionButton" });
    }
  }
</script>

<button on:click={handleAction}>Perform action</button>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: automatic route tracking covers SvelteKit's router, so test the default first. If a navigation is still not recorded, trigger it from `afterNavigate` in your root layout:

  ```svelte title="src/routes/+layout.svelte"
  <script>
    import { afterNavigate } from "$app/navigation";

    afterNavigate(() => {
      if (typeof window !== "undefined" && window.rybbit) {
        window.rybbit.pageview();
      }
    });
  </script>
  ```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Svelte (Vite / Client-Side) (/docs/guides/svelte/vite)





A client-side Svelte app built with Vite (`npm create vite@latest -- --template svelte`) serves a single `index.html` at the project root. Add the snippet there and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Svelte [#add-the-snippet-to-svelte]

    Open `index.html` at the root of your project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Svelte App</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/main.js"></script>
      </body>
    </html>
    ```

    Placing it just before `</body>` also works, but `<head>` lets the script start loading sooner.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any Svelte component:

```svelte title="src/lib/ActionButton.svelte"
<script>
  function handleAction() {
    if (window.rybbit) {
      window.rybbit.event("user_action", { component: "ActionButton" });
    }
  }
</script>

<button on:click={handleAction}>Perform action</button>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: Rybbit tracks History API and hash navigations, which covers routers such as `svelte-routing` and `svelte-spa-router`. If a route change is still not recorded, call `window.rybbit.pageview()` from that router's navigation callback.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Nuxt.js (/docs/guides/vue/nuxt)





Nuxt has two ways to load Rybbit: the [Nuxt Scripts](https://scripts.nuxt.com/scripts/rybbit-analytics) module, which ships a first-class Rybbit registry entry with a typed composable, or the `app.head.script` array in `nuxt.config.ts`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Nuxt [#add-the-snippet-to-nuxt]

    <Tabs items="[&#x22;Nuxt Scripts (Nuxt 3 and 4)&#x22;, &#x22;nuxt.config head&#x22;]">
      <Tab value="Nuxt Scripts (Nuxt 3 and 4)">
        Install the module. This adds `@nuxt/scripts` to the `modules` array in your `nuxt.config`:

        ```bash
        npx nuxi module add scripts
        ```

        Register Rybbit under `scripts.registry` with the site ID from your snippet:

        ```typescript title="nuxt.config.ts"
        export default defineNuxtConfig({
          modules: ["@nuxt/scripts"],
          scripts: {
            registry: {
              rybbitAnalytics: {
                siteId: "YOUR_SITE_ID",
                trigger: "onNuxtReady",
              },
            },
          },
        });
        ```

        Options:

        * `siteId` (required): your Rybbit site ID.
        * `autoTrackPageview`: track pageviews automatically (on by default).
        * `trackSpa`: track client-side route changes (on by default).
        * `analyticsHost`: script and API host for a self-hosted instance, for example `https://your-instance.com/api`.
        * `sessionReplay`, `webVitals`, `trackOutbound`: optional features.

        <Callout type="info">
          To keep the site ID out of source control, leave `siteId` unset and provide `NUXT_PUBLIC_SCRIPTS_RYBBIT_ANALYTICS_SITE_ID` in the environment; Nuxt Scripts reads it at runtime.
        </Callout>
      </Tab>

      <Tab value="nuxt.config head">
        Add the script to the `app.head.script` array in `nuxt.config.ts`:

        ```typescript title="nuxt.config.ts"
        export default defineNuxtConfig({
          app: {
            head: {
              script: [
                {
                  src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                  defer: true,
                },
              ],
            },
          },
        });
        ```

        On Nuxt 2 the array is `head.script` at the top level of `nuxt.config.js`, with the same entry.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

With Nuxt Scripts, use the `useScriptRybbitAnalytics` composable. Its `proxy` queues calls until the script is ready, so it is safe to call immediately:

```vue title="components/ActionButton.vue"
<template>
  <button @click="handleAction">Track action</button>
</template>

<script setup>
const { proxy } = useScriptRybbitAnalytics();

function handleAction() {
  proxy.event("nuxt_interaction", { detail: "User clicked the action button" });
}
</script>
```

With the `app.head.script` method, call `window.rybbit` directly and guard it with `import.meta.client`, since components also run on the server (on Nuxt 2 use `process.client`):

```vue title="components/ActionButton.vue"
<template>
  <button @click="handleAction">Track action</button>
</template>

<script setup>
function handleAction() {
  if (import.meta.client && window.rybbit) {
    window.rybbit.event("nuxt_interaction", { detail: "User clicked the action button" });
  }
}
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: both methods track Nuxt's client-side route changes automatically, so test the default first. If a route change is still not recorded, call `window.rybbit.pageview()` from a `router.afterEach` hook in a client plugin.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Vue.js (Vite / Client-Side) (/docs/guides/vue/vite)





A client-side Vue app built with Vite (`npm create vue@latest` or `npm create vite@latest -- --template vue`) serves a single `index.html` at the project root. Add the snippet there and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Vue.js [#add-the-snippet-to-vuejs]

    Open `index.html` at the root of your project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" href="/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Vue App</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/main.js"></script>
      </body>
    </html>
    ```

    Placing it just before `</body>` also works, but `<head>` lets the script start loading sooner.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component or method:

```vue title="src/components/ActionButton.vue"
<template>
  <button @click="trackAction">Track action</button>
</template>

<script setup>
function trackAction() {
  if (window.rybbit) {
    window.rybbit.event("custom_vue_action", { detail: "User performed an action" });
  }
}
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: Rybbit tracks Vue Router navigations automatically, so test the default first. If a route change is still not recorded, trigger it from an `afterEach` guard in your router setup:

  ```javascript title="src/router/index.js"
  import { createRouter, createWebHistory } from "vue-router";

  const router = createRouter({
    history: createWebHistory(import.meta.env.BASE_URL),
    routes: [/* your routes */],
  });

  router.afterEach(() => {
    if (window.rybbit) {
      window.rybbit.pageview();
    }
  });

  export default router;
  ```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Account settings (/de/docs/account-settings)







Access your account settings by clicking on "Account" or going to [app.rybbit.io/settings/account](https://app.rybbit.io/settings/account).

<img alt="account settings" src="__img0" />

## Account [#account]

### Name [#name]

Update your display name shown across the platform. This name is visible to other members in your organization.

### Email [#email]

Update your email address for account notifications and login. This is the primary email associated with your account.

### Weekly Email Reports <span className="text-green-500 text-sm">(Cloud)</span> [#weekly-email-reports-cloud]

Enable or disable automatic weekly email reports. When enabled, you'll receive a summary of your analytics performance delivered to your inbox each week.

### Sign Out [#sign-out]

Sign out of your current session.

## Security [#security]

### Change Password [#change-password]

Update your password to keep your account secure.

### Delete Account [#delete-account]

Permanently delete your account and all associated data.

<Callout type="warn">
  This action cannot be undone. If you have an active subscription, you must cancel it before deleting your account.
</Callout>

## API Keys [#api-keys]

Generate API keys to access Rybbit's analytics endpoints from your applications.

### Creating an API Key [#creating-an-api-key]

1. Enter a name for your API key (e.g., "Production App", "Development")
2. Optionally enable **Restrict permissions** to limit the key to specific resources. Leave it off for a full-access key that can do everything you can.
3. Click "Create"
4. Copy and save the generated key immediately

<Callout type="warn">
  On Rybbit Cloud, API keys require a Standard or Pro plan. On a free plan you'll see an upgrade prompt in place of the creation form.
</Callout>

<Callout type="warn">
  API keys are only shown once when created. Store your key securely as you won't be able to view it again.
</Callout>

### Managing API Keys [#managing-api-keys]

Your existing API keys are displayed in a table showing:

* **Name** - The name you assigned to the key
* **Key** - A preview of the key (first few characters)
* **Permissions** - Whether the key has full access or is restricted to specific scopes
* **Created** - When the key was created
* **Last used** - When the key last made a request

You can delete API keys that are no longer needed. Deleting a key immediately revokes access for any applications using it.

### Using API Keys [#using-api-keys]

Include your API key in requests to Rybbit's API endpoints. See the [API documentation](/docs/api) for available endpoints and usage examples.


# Autocapture (/de/docs/autocapture)



Rybbit can automatically capture common user interactions without requiring any code changes. These features can be enabled in your [Site Settings](/docs/site-settings) under the "Auto Capture" section.

## Available Autocapture Features [#available-autocapture-features]

| Feature           | Description                              | Event Type                    |
| ----------------- | ---------------------------------------- | ----------------------------- |
| Outbound Links    | Track clicks on external links           | `outbound`                    |
| Error Tracking    | Capture JavaScript errors and exceptions | `error`                       |
| Button Clicks     | Track clicks on buttons                  | `button_click`                |
| Copy Events       | Track when users copy text               | `copy`                        |
| Form Interactions | Track form submissions and input changes | `form_submit`, `input_change` |

## Outbound Links [#outbound-links]

When enabled, Rybbit automatically tracks clicks on links that navigate to external domains.

**Tracked properties:**

* `url` - The destination URL
* `text` - The link text
* `target` - The link target attribute (e.g., `_blank`, `_self`)

## Error Tracking [#error-tracking]

Captures uncaught JavaScript errors and unhandled promise rejections from your site. Only errors originating from your domain are tracked (third-party script errors are filtered out).

**Tracked properties:**

* `message` - The error message
* `stack` - Stack trace (truncated to 2000 characters)
* `fileName` - Source file where the error occurred
* `lineNumber` - Line number
* `columnNumber` - Column number

## Button Clicks [#button-clicks]

Automatically tracks clicks on:

* `<button>` elements
* Elements with `role="button"`
* `<input type="submit">` and `<input type="button">`

**Tracked properties:**

* `text` - The button's text content (falls back to `aria-label`, then `value` for input buttons, then `title`)

### Adding Custom Properties [#adding-custom-properties]

You can add custom properties to auto-tracked button clicks using `data-rybbit-prop-*` attributes:

```html
<button
  data-rybbit-prop-category="pricing"
  data-rybbit-prop-variant="blue"
>
  Buy Now
</button>
```

This tracks: `{ text: "Buy Now", category: "pricing", variant: "blue" }`

### Skipping Autocapture for Specific Buttons [#skipping-autocapture-for-specific-buttons]

If you want to track a button with a custom event instead of the automatic `button_click`, add the `data-rybbit-event` attribute:

```html
<!-- This button will fire a custom "signup" event, NOT a button_click -->
<button data-rybbit-event="signup" data-rybbit-prop-plan="pro">
  Sign Up
</button>
```

See [Track Events](/docs/track-events) for more details on custom event tracking.

## Copy Events [#copy-events]

Tracks when users copy text from your site using Ctrl+C, Cmd+C, or the context menu.

**Tracked properties:**

* `text` - The copied text (truncated to 500 characters)
* `textLength` - Original length of the copied text (only included if text was truncated)
* `sourceElement` - The HTML tag where the text was copied from (e.g., `p`, `div`, `span`)

## Form Interactions [#form-interactions]

Tracks two types of form events:

### Form Submissions (`form_submit`) [#form-submissions-form_submit]

Triggered when a form is submitted.

**Tracked properties:**

* `formId` - The form's `id` attribute
* `formName` - The form's `name` attribute
* `formAction` - The form's `action` URL
* `method` - HTTP method (GET, POST, etc.)
* `fieldCount` - Number of form fields
* `ariaLabel` - The form's `aria-label` attribute (if present)

You can add custom properties using `data-rybbit-prop-*` on the form element:

```html
<form
  id="signup"
  data-rybbit-prop-form-type="registration"
  data-rybbit-prop-variant="a"
>
  ...
</form>
```

### Input Changes (`input_change`) [#input-changes-input_change]

Triggered when a user changes the value of an input, select, or textarea field. Disabled inputs are automatically excluded from tracking.

**Tracked properties:**

* `element` - The element type (`input`, `select`, or `textarea`)
* `inputType` - For inputs: the type attribute (e.g., `text`, `email`, `checkbox`)
* `inputName` - The field's `name`, `id`, `aria-label`, or `placeholder` attribute (first available)
* `formId` - The parent form's `id` (if within a form)
* `formName` - The parent form's `name` (if within a form)

You can add custom properties using `data-rybbit-prop-*` on the input element:

```html
<input
  name="email"
  data-rybbit-prop-field-category="contact"
/>

<select
  name="country"
  data-rybbit-prop-section="demographics"
>
  ...
</select>
```

**Privacy note:** Hidden inputs, password fields, and disabled inputs are automatically excluded from tracking.

## Enabling Autocapture [#enabling-autocapture]

1. Go to your site's **Settings**
2. Navigate to the **Auto Capture** section
3. Toggle on the features you want to enable

Changes take effect immediately for new visitors. Existing sessions may need to refresh to pick up the new configuration.

***

**Related Documentation:**

* [Track Events](/docs/track-events) - Manual event tracking
* [Site Settings](/docs/site-settings) - Configure your site
* [Behavior Analytics - Events](/docs/behavior-analytics/events) - View captured events


# Billing (/de/docs/billing-settings)





Access billing settings by hovering over the sidebar and clicking "Billing".

Subscriptions are scoped to a single organization. If you have multiple organizations, each one requires its own subscription. Switching organizations will show that organization's subscription status.


# Bot detection (/de/docs/bot-detection)





Rybbit can filter bot traffic before it reaches your normal analytics. When **Block Bot Traffic** is enabled for a site, each incoming tracking request is checked by several detection layers. If any layer identifies the request as bot traffic, the request is excluded from the normal analytics tables and stored separately for bot traffic inspection.

## Enabling Bot Detection [#enabling-bot-detection]

Bot blocking is configured per site:

1. Open your site in the Rybbit dashboard
2. Go to **Site Settings**
3. Enable **Block Bot Traffic**

When this setting is off, Rybbit does not block requests based on bot detection.

## What Happens to Detected Bots [#what-happens-to-detected-bots]

Detected bot requests are not added to your normal analytics data. This keeps dashboard totals, reports, journeys, funnels, session lists, and usage metrics focused on human traffic.

Detected bot visits also do not count toward billable analytics usage. If bot blocking filters a request, you are not charged for that bot visit.

Rybbit still stores a compact bot event record so you can inspect what was filtered. Bot event records include route, device, location, ASN, and which detection layers matched.

## Detection Layers [#detection-layers]

Rybbit runs all detection layers before making a final decision. A request can match multiple layers, and the bot event records every layer that matched.

<Steps>
  <Step>
    ### User-Agent Patterns [#user-agent-patterns]

    The `ua_pattern` layer checks the request user-agent against known bot, crawler, AI agent, SEO tool, monitoring, social preview, framework, and headless browser patterns.

    Examples include:

    * Search engine crawlers
    * Headless browser user-agents
    * AI crawler and agent user-agents
    * SEO and monitoring tools
    * Script or framework HTTP clients
  </Step>

  <Step>
    ### Header Heuristics [#header-heuristics]

    The `header_heuristics` layer scores request headers for browser consistency.

    It looks for signals such as:

    * Missing browser headers
    * Suspicious fetch metadata
    * Inconsistent browser claims
    * Headless or automation-looking headers
    * Stale or unusual Chrome versions
    * Script/framework-style requests that do not look like normal browser traffic

    This layer is useful because many bots use a browser-like user-agent but do not send the full set of headers a real browser normally sends.
  </Step>

  <Step>
    ### Client Signals [#client-signals]

    The `client_signals` layer uses lightweight browser-side signals collected by the tracking script.

    Signals include:

    * Automation APIs
    * Zero or impossible window dimensions
    * Default automation viewport sizes such as `800x600` and `1024x768`
    * Suspicious outer window dimensions
    * Missing browser APIs
    * Missing Chrome globals
    * SwiftShader renderer signals
    * Empty plugin lists

    Rybbit combines these into a weighted score. Strong signals can identify bot traffic on their own, while weaker signals contribute supporting evidence.
  </Step>

  <Step>
    ### ASN and Network Signals [#asn-and-network-signals]

    The `bot_asn` layer uses ASN metadata from the resolved IP address.

    There are two kinds of ASN matches:

    * **Curated bot provider ASNs**: Known AI, scanner, and internet measurement providers can trigger bot detection directly.
    * **Generic hosting/datacenter ASNs**: Hosting ASNs are treated as supporting evidence. They are recorded when another bot layer also matches, but generic hosting ASN alone is not enough to block a request.

    This avoids filtering every legitimate visitor who happens to browse through a cloud, CDN, VPN, corporate gateway, or first-party proxy, while still preserving ASN context when other bot evidence exists.
  </Step>

  <Step>
    ### Rate and Anomaly Detection [#rate-and-anomaly-detection]

    The `rate_anomaly` layer watches for bursty or crawl-shaped behavior.

    It tracks short rolling windows for patterns such as:

    * Too many events from the same IP and user-agent
    * Too many events from the same IP
    * Too many distinct paths visited quickly
    * Too many different user-agents from one IP
    * Too many hostnames from one IP
    * High site-wide volume from one user-agent
    * Large volumes of requests missing client-side bot scores

    This layer is designed to catch fast crawlers, floods, and replayed tracking requests that may not have obvious user-agent or browser fingerprint signals.
  </Step>
</Steps>

## Bot Identity [#bot-identity]

Every detected bot carries the layers that caught it. Bots matched by one of Rybbit's curated user-agent patterns carry three more fields, which is what the Bots dashboard groups by:

| Field          | Example       | Meaning                                      |
| -------------- | ------------- | -------------------------------------------- |
| `bot_name`     | `GPTBot`      | The name the bot publishes in its user agent |
| `bot_operator` | `OpenAI`      | Who runs it                                  |
| `bot_purpose`  | `ai_training` | What the fetch is for                        |

A bot matched only by a broad pattern (`crawl`, `spider`) is still filtered, but has no published identity — those rows read as **Unnamed**, which is more useful than a guess.

### Purposes [#purposes]

`bot_purpose` answers a different question from `bot_category`. Category groups bots into families; purpose says what the operator does with the page, which is the distinction that matters for AI traffic:

| Purpose          | What it means                                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ai_training`    | Collecting pages to train a model. Sends no readers back. Examples: GPTBot, ClaudeBot, CCBot, Google-Extended, Bytespider                                       |
| `ai_search`      | Indexing pages so an assistant can cite them. Can send readers back. Examples: OAI-SearchBot, Claude-SearchBot, PerplexityBot                                   |
| `ai_agent`       | A person asked an assistant to open the page, and it fetched it there and then. Examples: ChatGPT-User, Claude-User, Perplexity-User, Google-Agent, Claude Code |
| `search`         | Classic search engine indexing                                                                                                                                  |
| `social_preview` | Link unfurling                                                                                                                                                  |
| `seo`            | Backlink, rank, and site-audit crawlers                                                                                                                         |
| `monitoring`     | Uptime, synthetic, and performance checks                                                                                                                       |
| `security`       | Scanners                                                                                                                                                        |
| `scripted`       | HTTP libraries and CLI clients                                                                                                                                  |
| `headless`       | Browser automation                                                                                                                                              |

Splitting the AI family in three is the point: a training crawler reading 4,000 pages and a person's assistant opening one page are both `category: ai`, but they mean opposite things for your site.

<Callout>
  These fields were added in a later release. Bot events recorded before then have empty identity fields and appear as **Unnamed** / **Unclassified**; nothing is backfilled.
</Callout>

## How Decisions Are Made [#how-decisions-are-made]

Rybbit does not stop at the first matching layer. It runs every layer, records all matches, and then makes one final decision.

A request is marked as bot traffic when at least one blocking layer matches. The resulting bot event includes boolean fields for each layer:

* User-agent pattern
* Header heuristics
* Client signals
* Bot ASN
* Rate anomaly

Because multiple layers can match the same request, per-layer bot counts can add up to more than the total number of bot requests.

## Server-Side Tracking [#server-side-tracking]

Requests sent to `/api/track` with `Authorization: Bearer <api key>` and a valid API key are treated as trusted server-side ingestion. Four of the five layers are skipped: the headers, the client signals, the network address, and the request rate all belong to your server, not to the visitor it is reporting, so scoring them would convict your own backend.

The user-agent layer still runs, on the `user_agent` you send. Nothing changes for ordinary backend events — a request reporting a real browser's user agent is tracked normally.

### Reporting crawlers that never run JavaScript [#reporting-crawlers-that-never-run-javascript]

Rybbit's tracker is JavaScript, so a crawler that fetches your HTML and executes nothing never reaches Rybbit at all. Most AI training crawlers work exactly that way, which is why the Bots dashboard carries a note about its own coverage.

If you want to see them, report them from the edge — middleware, a worker, or a reverse proxy — forwarding the real request's `user_agent`:

```json
{
  "site_id": "1",
  "hostname": "example.com",
  "pathname": "/pricing",
  "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.2; +https://openai.com/gptbot"
}
```

A forwarded crawler user agent is classified and lands in your bot events with full identity, rather than in your analytics as a phantom visitor.

<Callout type="warn">
  Do not expose API keys in browser JavaScript. API keys are only for server-side requests.
</Callout>

## Proxies and CDN Setups [#proxies-and-cdn-setups]

If you proxy Rybbit through Cloudflare Workers, AWS CloudFront, Nginx, Caddy, or another reverse proxy, forward the original visitor IP:

```txt
X-Forwarded-For: <visitor-ip>
X-Real-IP: <visitor-ip>
```

Also preserve the original `User-Agent`, `Referer`, and `Accept-Language` headers where possible.

If the proxy IP is sent instead of the visitor IP, traffic may be geolocated to the proxy location and may inherit the proxy provider's ASN.

See the [proxy troubleshooting guide](/docs/proxy-guide/troubleshooting) for examples.

## What Bot Detection Does Not Guarantee [#what-bot-detection-does-not-guarantee]

Bot detection improves analytics quality, but no bot filter is perfect.

Some sophisticated bots can look like normal browsers. Some legitimate users may browse through unusual network paths or constrained browser environments. Rybbit uses multiple layers to reduce both misses and false positives, but you should still interpret bot counts as an operational signal rather than an exact measurement of all automation on your site.


# Comparison (/de/docs/comparison)





| Feature                           | Rybbit                                                             | GA4                                                                | Plausible                                                            | Cloudflare                                                         |
| --------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Open Source**                   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Self-Hosting**                  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />\* | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Cookieless & Privacy friendly** | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Advanced Maps**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Advanced Filters**              | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Limited</span>    | <span className="inline-flex items-center gap-1">Limited</span>      | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Web Vitals**                    | <span className="inline-flex items-center gap-1">Paid</span>       | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Session Details**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **User Profiles**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Session Replays**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Funnels**                       | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Paid</span>         | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **User Journeys**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Retention Analysis**            | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Goals & Events**                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Real-time Dashboard**           | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Custom Events (JSON)**          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Limited</span>      | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Error Tracking**                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Public Dashboards**             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Organizations**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Frog 🐸**                       | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |

\* Plausible's Community Edition has very limited features compared to their cloud version


# Data Import (/de/docs/data-import)





The data import feature allows you to migrate your historical analytics data from other platforms to Rybbit. This preserves your analytics history when switching from competitors, giving you a complete view of your data without losing valuable insights.

## Supported Platforms [#supported-platforms]

Currently, Rybbit supports importing data from:

* Umami
* Simple Analytics
* Plausible

Additional platforms may be added in the future based on user demand.

<Callout type="info">
  Umami and Simple Analytics are imported from a CSV export, while Plausible is imported from its ZIP export. The Import dialog automatically expects the correct file type for the platform you select.
</Callout>

## Plan Requirements [#plan-requirements]

### Cloud Version [#cloud-version]

| Plan     | Access          | Historical Window   | Monthly Event Limit |
| -------- | --------------- | ------------------- | ------------------- |
| Free     | ❌ Not available | -                   | -                   |
| Standard | ✅ Available     | 36 months (3 years) | Plan limit applies  |
| Pro      | ✅ Available     | 60 months (5 years) | Plan limit applies  |

### Self-Hosted Version [#self-hosted-version]

Self-hosted installations have **unlimited** access to data imports with no restrictions on:

* Historical data window (import data from any date)
* Event quotas (no monthly limits)
* Concurrent imports (no limit on active imports)

## Import Limits [#import-limits]

### Historical Data Windows [#historical-data-windows]

The historical data window determines how far back you can import data:

* **Standard plans**: Import data from the past 36 months (3 years)
* **Pro plans**: Import data from the past 60 months (5 years)
* **Self-hosted**: Unlimited - import data from any date

Events outside your plan's historical window will be automatically skipped during import.

### Event Quotas [#event-quotas]

Imported events count toward your monthly event limit:

* If you're close to your monthly limit, imports may be partially skipped
* Skipped events are counted and displayed in the import history
* Consider upgrading your plan if you need to import large amounts of data

### Concurrent Imports [#concurrent-imports]

For cloud users:

* **Maximum 1 active import per organization**
* New imports are blocked until the current one completes
* Maximum 2-hour timeout per import

Self-hosted users have no concurrent import restrictions.

## How to Import Data [#how-to-import-data]

<Steps>
  <Step>
    ### Export Data from Source Platform [#export-data-from-source-platform]

    **Umami:**

    1. Navigate to Settings → Data
    2. Export your data as CSV
    3. Ensure the export includes all required fields

    **Simple Analytics:**

    1. Go to your site settings
    2. Navigate to Export section
    3. Download your analytics data as CSV

    **Plausible:**

    1. Open your site's dashboard
    2. Use the CSV export option to download your data
    3. Keep the exported **ZIP** archive as-is — do not unzip it
  </Step>

  <Step>
    ### Navigate to Import Settings [#navigate-to-import-settings]

    1. Open your Rybbit dashboard
    2. Navigate to Site Settings
    3. Click on the **Import** tab
  </Step>

  <Step>
    ### Select Platform and Upload File [#select-platform-and-upload-file]

    1. Select your source platform from the dropdown
    2. Click "Choose File" and select your exported file (a **CSV** for Umami and Simple Analytics, or a **ZIP** for Plausible)
    3. Click the **Import** button

    <Callout type="warn">
      For very large imports (multiple GB), consider splitting your CSV into smaller files and importing them sequentially.
    </Callout>
  </Step>

  <Step>
    ### Monitor Import Progress [#monitor-import-progress]

    Your import will begin processing in the background. You can:

    * View the import status in the "Import History" section
    * Monitor the number of imported, skipped, and invalid events
    * Continue using Rybbit while the import runs

    <Callout type="info">
      Large imports may take several minutes to complete. The page will automatically refresh to show updated progress.
    </Callout>
  </Step>
</Steps>

## Import History [#import-history]

The Import History section displays all your past and current imports.

### Import Metrics [#import-metrics]

Each import shows three key metrics:

**Imported Events**

* Number of events successfully imported into Rybbit
* These events are now visible in your analytics dashboard

**Skipped Events**

* Events that were excluded during import
* Common reasons:
  * Outside your plan's historical data window
  * Would exceed your monthly event quota

**Invalid Events**

* Events that failed validation during import
* Common reasons:
  * Malformed CSV data
  * Missing required fields
  * Invalid date/time formats
  * Data type mismatches

<Callout type="warn">
  If you see a high number of invalid events, verify your CSV export matches the expected format for your platform.
</Callout>

### Managing Imports [#managing-imports]

**Deleting Completed Imports**

* Click the trash icon next to any completed import
* Confirm the deletion in the dialog
* This will permanently remove the import record **and all associated events** from your analytics
* Active imports cannot be deleted

<Callout type="error">
  Deleting an import removes all events that were imported. This action cannot be undone. Make sure you have a backup of your original CSV file.
</Callout>

## Troubleshooting [#troubleshooting]

### Events Skipped Due to Quota Limits [#events-skipped-due-to-quota-limits]

**Cause:** Importing the events would exceed your monthly event limit.

**Solution:**

* Wait until the next billing cycle when your quota resets
* Upgrade to a plan with a higher event limit
* Import smaller date ranges to stay within quota

### Events Skipped Due to Date Range [#events-skipped-due-to-date-range]

**Cause:** Events are older than your plan's historical data window.

**Solution:**

* Upgrade to Pro plan for 60-month history (vs 24-month on Standard)
* For self-hosted, no action needed - all dates are allowed
* Filter your CSV export to only include recent data

### High Invalid Event Count [#high-invalid-event-count]

**Cause:** CSV format doesn't match the expected structure for your platform.

**Solution:**

1. Verify you selected the correct platform
2. Check that your CSV export includes all required fields
3. Look for special characters or malformed data in the CSV
4. Try importing a small sample file (first 100 rows) to test

### Import Appears Stuck [#import-appears-stuck]

**Cause:** Very large files can take time to process, or a timeout occurred.

**Solution:**

* Wait up to 2 hours for the import to complete
* If still stuck after 2 hours, the import will be automatically marked as complete
* Check the imported event count to see if any data was processed
* Contact support if no events were imported

## Best Practices [#best-practices]

### Before You Import [#before-you-import]

1. **Export a complete backup** from your current analytics platform
2. **Test with a small sample** (first 1,000 rows) before importing your full dataset
3. **Check your event quota** to ensure you have sufficient capacity
4. **Verify date ranges** match your plan's historical window
5. **Review CSV format** matches the required structure for your platform

### During Import [#during-import]

1. **Don't close the browser tab**
2. **Monitor the progress** in the Import History section
3. **Check for skipped/invalid events** early to catch format issues
4. **Wait for completion** before starting another import (cloud users)

### After Import [#after-import]

1. **Verify your data** appears correctly in analytics dashboards
2. **Check date ranges** to ensure historical data is visible
3. **Compare totals** with your source platform to validate accuracy
4. **Keep the original CSV** as a backup before deleting the import


# Definitions (/de/docs/definitions)



## Aggregate Metrics [#aggregate-metrics]

### Unique Users [#unique-users]

The total number of distinct individuals who visited your website, identified by a unique user ID. Each user is counted only once regardless of how many times they visit.

### Sessions [#sessions]

A series of user interactions with your website within a given time frame. A session ends after 30 minutes of inactivity from the same user ID. Multiple pageviews can occur within one session.

### Pageviews [#pageviews]

The total number of times visitors have viewed pages on your website. Each time a page is loaded or reloaded counts as a pageview.

### Pages Per Session [#pages-per-session]

The average number of pages viewed during a session. Calculated by dividing the total number of pageviews by the total number of sessions.

### Bounce Rate [#bounce-rate]

The percentage of sessions where a user leaves your site after viewing only one page without any interaction. A high bounce rate might indicate that landing pages aren't relevant to visitors.

### Session Duration [#session-duration]

The average length of time users spend on your site during a session. Longer sessions typically indicate more engaged visitors.

## Individual Datapoints [#individual-datapoints]

### User ID [#user-id]

A unique identifier generated from a hash of the visitor's IP address and browser user-agent. This anonymized ID helps track unique visitors without storing personally identifiable information.

### Hostname [#hostname]

The domain name of the website being visited (e.g., example.com).

### Pathname [#pathname]

The path portion of the URL that follows the hostname (e.g., /blog/article).

### Entry Page [#entry-page]

The first page viewed by a user during a session. Identifies which pages commonly serve as entry points to your site.

### Exit Page [#exit-page]

The last page viewed by a user before ending their session. Helps identify where users tend to leave your site.

### Querystring [#querystring]

The portion of a URL that follows a question mark, containing parameters (e.g., ?utm\_source=newsletter).

### Page Title [#page-title]

The title of the webpage as defined in the HTML `<title>` tag.

### Referrer [#referrer]

The URL that a user was on before coming to your site. Shows how users are discovering your content.

### UTM Source [#utm-source]

Identifies which website, search engine, or other source is sending traffic to your site (e.g., google, newsletter, twitter).

### UTM Medium [#utm-medium]

Identifies the marketing medium (e.g., cpc, email, social).

### UTM Term [#utm-term]

Identifies paid search keywords. Used primarily for paid search campaigns.

### UTM Campaign [#utm-campaign]

Identifies the specific campaign or promotion that brought users to your site.

### UTM Content [#utm-content]

Identifies what specifically was clicked to bring the visitor to your site (e.g., banner ad, text link).

### Channel [#channel]

A categorization of traffic sources into standard groups such as direct, search, social, email, or referral.

### Browser [#browser]

The web browser used by the visitor (e.g., Chrome, Firefox, Safari).

### Browser Version [#browser-version]

The specific version of the browser being used.

### Operating System [#operating-system]

The operating system used by the visitor (e.g., Windows, macOS, iOS, Android).

### Operating System Version [#operating-system-version]

The specific version of the operating system being used.

### Language [#language]

The preferred language setting of the visitor's browser.

### Country [#country]

The country where the user is located, based on IP geolocation.

### Region [#region]

The state or region where the user is located, based on IP geolocation.

### City [#city]

The city where the user is located, based on IP geolocation.

### Latitude [#latitude]

The geographic latitude coordinate of the user's approximate location.

### Longitude [#longitude]

The geographic longitude coordinate of the user's approximate location.

### Screen Width [#screen-width]

The width of the visitor's screen or device viewport in pixels.

### Screen Height [#screen-height]

The height of the visitor's screen or device viewport in pixels.

### Device Type [#device-type]

The type of device being used (e.g., desktop, tablet, mobile).

### Event Name [#event-name]

The name of a custom event triggered by user interaction (e.g., "button\_click", "form\_submit").

### Event Properties [#event-properties]

Additional contextual data associated with custom events, stored as key-value pairs. Used to provide more detail about specific interactions.


# Embeds (/de/docs/embed-widget)



Rybbit supports two iframe embed options:

* [Widget Embeds](/docs/embeds/widget) show a compact live visitor widget on any web page.
* [Dashboard Embed](/docs/embeds/dashboard) shows your analytics dashboard in an iframe.

Both embeds are self-contained iframes. There is no script tag, no JavaScript on your site, and no dependency on the Rybbit tracking script.

## Which Embed Should I Use? [#which-embed-should-i-use]

Use [Widget Embeds](/docs/embeds/widget) when you want a small live visitor count, chart, or top-countries summary. Widget Embeds do not make your dashboard public.

Use [Dashboard Embed](/docs/embeds/dashboard) when you want to publish the full read-only analytics dashboard. Dashboard Embed uses a generated private link, so Public Analytics is not required.


# Experiments (/de/docs/experiments)





Experiments are A/B tests built on top of Rybbit. Each experiment splits your visitors across the variants of a [multivariate feature flag](/docs/feature-flags), then measures how often each variant completes a [conversion goal](/docs/goals). Rybbit calculates the conversion rate for every variant, the **lift** relative to your control, and how confident you can be that the difference is real.

<Callout type="info">
  An experiment ties together two features you may already use: a **multivariate feature flag** decides which variant each visitor sees, and a **goal** defines the conversion you are optimizing for. If you understand those two pieces, you understand experiments.
</Callout>

## How Experiments Work [#how-experiments-work]

An experiment has three moving parts:

| Part           | What it does                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assignment** | A multivariate feature flag assigns each visitor to one stable variant (for example `control` or `variant_a`) based on its rollout percentages.                                                   |
| **Exposure**   | When your code reads the flag with `rybbit.flag()`, Rybbit records an exposure for that variant. The number of distinct sessions exposed to a variant is the denominator for its conversion rate. |
| **Conversion** | The experiment's primary goal — a page visit or a custom event — counts as a conversion for whichever variant the visitor was assigned.                                                           |

Because assignment is sticky for a given visitor, a person sees the same variant on repeat visits, which keeps your results consistent.

## Creating an Experiment [#creating-an-experiment]

Open your site in the Rybbit dashboard, go to **Experiments**, and click **New experiment**. A guided wizard walks you through each step.

<Steps>
  <Step>
    ### Basics [#basics]

    Give the experiment a **name** and, optionally, a **hypothesis** and **description*&#x2A;. The hypothesis is internal context for your team — something like &#x2A;"Changing the CTA copy will increase signups."* It does not affect assignment or tracking.

    New experiments are created as **drafts** so you can add the implementation code before any traffic is split.
  </Step>

  <Step>
    ### Assignment [#assignment]

    Choose how visitors are split into variants:

    * **Create a new flag** — Define a new multivariate flag with its own variants and rollout split. Each variant needs a unique key, and the rollout percentages must add up to &#x2A;*100%**.
    * **Use an existing flag** — Pick a multivariate flag that is not already attached to another experiment.

    <Callout type="info">
      Each experiment uses its own multivariate flag. The flag's variant keys (such as `control` and `variant_a`) are what you branch on in code.
    </Callout>
  </Step>

  <Step>
    ### Goal [#goal]

    Pick the conversion you want to compare variants against:

    * **Create a new goal** — Define a **page goal** (a URL path such as `/signup/complete`) or an **event goal** (a custom event such as `signup_completed`). The form provides autocomplete suggestions based on paths and events already seen on your site.
    * **Use an existing goal** — Connect a goal you already track.
    * **Skip for now** — Create the experiment without a goal and add one later. Conversion results require a goal.
  </Step>

  <Step>
    ### Review and Implement [#review-and-implement]

    Review the assignment flag and goal, then create the experiment. Rybbit creates any new flag or goal you configured, connects them, and shows you the **implementation code** for the flag. The experiment stays in **draft** until you start it from the experiment list.
  </Step>
</Steps>

## Implementing in Code [#implementing-in-code]

Read the experiment's flag in your app and branch your UI or behavior on the returned variant. Reading the flag also records the exposure that powers your results, so make sure it runs wherever the tested experience is shown.

<Tabs items="['JavaScript', 'TypeScript']">
  <Tab value="JavaScript">
    ```javascript
    window.rybbit.onReady((rybbit) => {
      const variant = rybbit.flag("checkout_cta", "control");

      if (variant === "variant_a") {
        // Render the variant experience.
      } else {
        // Render the control experience.
      }
    });
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript
    type ExperimentVariant = "control" | "variant_a";

    window.rybbit.onReady((rybbit) => {
      const variant = rybbit.flag("checkout_cta", "control") as ExperimentVariant;

      switch (variant) {
        case "variant_a":
          // Render the variant experience.
          break;
        default:
          // Render the control experience.
          break;
      }
    });
    ```
  </Tab>
</Tabs>

If your primary goal is an **event goal**, fire that event when the conversion action happens:

```javascript
window.rybbit.onReady((rybbit) => {
  rybbit.event("signup_completed");
});
```

**Page goals** need no extra code — Rybbit counts sessions that reach the goal's path automatically.

<Callout type="info">
  Use a stable variant for the `rybbit.flag()` fallback (usually `"control"`) so visitors still get a sensible experience before the flag resolves or if the experiment is paused.
</Callout>

## Reading Results [#reading-results]

Each experiment shows a results panel comparing every variant. Results respect the global date range and filters applied on the page.

| Metric              | Description                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Variant**         | The variant key, with the **Control** marked as the baseline.                                                         |
| **Sessions**        | Sessions exposed to that variant, alongside the number that converted.                                                |
| **Conversion rate** | Conversions divided by the number of exposed sessions (the **Sessions** figure) for that variant.                     |
| **Lift**            | The percentage change in conversion rate relative to the control. Positive lift is shown in green, negative in red.   |
| **Confidence**      | How confident Rybbit is that the variant's difference from the control is real, based on a two-proportion comparison. |

Rybbit summarizes the state of each experiment at a glance:

* **Gathering data** — Not enough exposures or conversions yet to draw a conclusion.
* **Leading** — A variant is outperforming the control with at least **95% confidence**.
* **Winner** — The variant recorded as the winner once the experiment is decided.

<Callout type="warn">
  Avoid stopping an experiment the moment a variant looks ahead. Let it run until it reaches 95% confidence with a meaningful number of conversions, otherwise early noise can masquerade as a real difference.
</Callout>

## Experiment Lifecycle [#experiment-lifecycle]

Experiments move through four statuses, which you control from the experiment list:

| Status        | Meaning                                                                                 |
| ------------- | --------------------------------------------------------------------------------------- |
| **Draft**     | Created but not yet collecting results. Add your implementation code here.              |
| **Running**   | Actively splitting traffic and recording exposures and conversions.                     |
| **Paused**    | Temporarily stopped. Visitors keep their existing assignments.                          |
| **Completed** | Finished. Use this once you have a result and have shipped (or rolled back) the change. |

Use **Start**, **Pause**, and **Complete** on each experiment to move between states.

## Best Practices [#best-practices]

* Change one thing at a time so you can attribute any lift to a single difference.
* Make sure your variant rollout percentages add up to 100% unless you intentionally want unassigned traffic.
* Read the flag wherever the tested experience renders so every exposed visitor is counted.
* Pick a primary goal that directly reflects the outcome you care about, not a proxy metric.
* Wait for 95% confidence and a healthy sample size before declaring a winner.
* After completing an experiment, ship the winning variant and remove the flag branch to keep your code clean.

***

**Related Documentation:**

* [Feature Flags](/docs/feature-flags) — The assignment mechanism behind experiments
* [Goals](/docs/goals) — Define the conversion an experiment measures
* [Track Events](/docs/track-events) — Fire custom events for event goals
* [Tracking Script](/docs/script) — Load the script and use `onReady()`


# Feature Flags (/de/docs/feature-flags)





Feature flags let you change product behavior without deploying new code. In Rybbit, a flag can be evaluated in the browser, on your server, or in both places. Flag assignments are also attached to analytics events so you can filter and compare behavior by flag value.

<Callout type="info">
  Feature flags are different from [tags](/docs/tagging). Tags label traffic that you already routed yourself. Feature flags decide which value a visitor receives at runtime.
</Callout>

## Create a Flag [#create-a-flag]

1. Open your site in the Rybbit dashboard.
2. Go to **Feature Flags**.
3. Click **New flag**.
4. Choose a stable **key**, such as `new_checkout` or `pricing_banner`.
5. Select the flag type, runtime, and targeting conditions.
6. Enable the flag when you are ready for it to evaluate as active.

The **key** is the public identifier used in code. Treat it as the flag name and avoid changing it after the flag is in use.

## Flag Types [#flag-types]

| Type                  | Returns                                         | Best for                                                                  |
| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
| **Boolean**           | `true` or `false`                               | Releasing a feature on/off, gradual rollouts, allowlists                  |
| **Multiple variants** | A variant key like `"control"` or `"variant_a"` | Comparing more than one experience or configuration                       |
| **Remote config**     | `true` plus a payload from `flagPayload()`      | Shipping structured config such as copy, colors, limits, or JSON settings |

### Boolean Flags [#boolean-flags]

Boolean flags support a rollout percentage for each condition set. If the visitor matches the condition set and falls inside the rollout bucket, `window.rybbit.flag()` returns `true`.

```javascript
window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);

  if (enabled) {
    showNewCheckout();
  }
});
```

### Multiple Variants [#multiple-variants]

Multiple variant flags return the selected variant key. Each variant has its own rollout percentage and optional payload.

```javascript
window.rybbit.onReady((rybbit) => {
  const variant = rybbit.flag("homepage_cta", "control");

  if (variant === "variant_a") {
    renderAlternateCTA();
  }
});
```

Variant rollout percentages are evaluated in order. If the visitor falls outside the total allocated percentage, the flag returns `false`.

### Remote Config [#remote-config]

Remote config flags are useful when you want Rybbit to choose a JSON payload. For remote config, `flag()` returns whether a config matched, and `flagPayload()` returns the actual config.

```javascript
window.rybbit.onReady((rybbit) => {
  const config = rybbit.flagPayload("checkout_config", {
    buttonText: "Continue",
    theme: "default",
  });

  renderCheckout(config);
});
```

Remote config can still use targeting. This lets you serve one config to beta users, another config to a country, and a default config to everyone else.

## Runtime [#runtime]

Each flag has a runtime:

| Runtime    | Evaluated by                 | Use when                                                       |
| ---------- | ---------------------------- | -------------------------------------------------------------- |
| **Client** | The browser tracking script  | UI changes, frontend copy, client-only experiments             |
| **Server** | Your backend through the API | Backend behavior, pricing logic, data access, anything private |
| **Both**   | Browser and server           | Both sides need the same decision                              |

<Callout type="warn">
  Do not put secrets in client or both-runtime flag payloads. Browser-evaluated flags and payloads are visible to the user.
</Callout>

## Targeting and Condition Sets [#targeting-and-condition-sets]

Flags use ordered condition sets. Each set contains targeting rules plus the rollout, variants, or payload for users who match that set.

Evaluation works like this:

1. Rybbit checks condition sets from top to bottom.
2. The first condition set whose rules all match is selected.
3. Rybbit applies the rollout, variant allocation, or remote config payload from that selected set.
4. Later condition sets are not evaluated.

This means condition set order matters. Put narrow segments first and broad defaults last.

<Callout type="warn">
  If a visitor matches a boolean condition set but falls outside that set's rollout percentage, Rybbit returns `false` and does not continue to later condition sets.
</Callout>

### Targeting Fields [#targeting-fields]

| Field           | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| Hostname        | Current hostname, such as `example.com`                          |
| Pathname        | Current path, such as `/pricing`                                 |
| Query parameter | A specific URL query parameter                                   |
| Referrer        | The document referrer                                            |
| Language        | Browser language, such as `en-US`                                |
| Country         | Visitor country resolved from IP                                 |
| Region          | Visitor region resolved from IP                                  |
| City            | Visitor city resolved from IP                                    |
| Device type     | Device category derived from user agent and screen size          |
| User ID         | The identified user ID, falling back to the anonymous visitor ID |
| User trait      | A trait set through `identify()` or `setTraits()`                |

### Operators [#operators]

Targeting rules support:

* `equals`
* `not_equals`
* `contains`
* `starts_with`
* `ends_with`
* `regex`

All rules in a condition set must match. Multiple condition sets act as ordered alternatives.

## Browser Runtime [#browser-runtime]

The tracking script automatically evaluates client and both-runtime flags when it loads. It sends context such as anonymous visitor ID, identified user ID, URL, referrer, language, screen size, IP-derived location, and saved user traits.

Use `onReady()` before reading flags if you need the evaluated value during page initialization:

```javascript
window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);
  const payload = rybbit.flagPayload("new_checkout", {});
});
```

Available browser methods:

<TypeTable
  type="{
  &#x22;flag(key, fallback)&#x22;: {
    description: &#x22;Returns a single flag value. Reading a flag also records a feature flag exposure event once per flag value/version.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flagPayload(key, fallback)&#x22;: {
    description: &#x22;Returns the payload for a flag or variant. Use this for remote config and multivariate payloads.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flags()&#x22;: {
    description: &#x22;Returns all evaluated flag values keyed by flag key.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flagPayloads()&#x22;: {
    description: &#x22;Returns all available flag payloads keyed by flag key.&#x22;,
    type: &#x22;function&#x22;,
  },
}"
/>

Assignments are included on analytics events as a feature flag map. This lets you filter dashboard reports by flag key and value.

### Identify and Traits [#identify-and-traits]

If you call `identify()` or `setTraits()`, the browser runtime refreshes feature flags using the updated user context.

```javascript
window.rybbit.identify("user_123", {
  plan: "pro",
  beta: true,
});
```

You can then target flags using **User ID** or **User trait** rules.

## Server Runtime [#server-runtime]

Use server runtime for decisions that should not happen in the browser. The server endpoint returns server and both-runtime flags only.

```
POST /api/sites/:siteId/feature-flags/evaluate
```

### Request [#request]

<TypeTable
  type="{
  anonymousId: {
    description: &#x22;Stable anonymous visitor ID used for rollout bucketing. Keep this stable for sticky assignments.&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  identifiedUserId: {
    description: &#x22;Logged-in user ID. Enables user ID rules and loads saved user traits.&#x22;,
    type: &#x22;string&#x22;,
  },
  hostname: {
    description: &#x22;Hostname used by hostname targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  pathname: {
    description: &#x22;Path used by pathname targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  query: {
    description: &#x22;Parsed query parameter object used by query targeting rules.&#x22;,
    type: &#x22;Record<string, string>&#x22;,
  },
  querystring: {
    description: &#x22;Raw query string. Used if query is not provided.&#x22;,
    type: &#x22;string&#x22;,
  },
  referrer: {
    description: &#x22;Referrer used by referrer targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  language: {
    description: &#x22;Language code used by language targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  screenWidth: {
    description: &#x22;Screen width used with user agent parsing to derive device type.&#x22;,
    type: &#x22;number&#x22;,
  },
  screenHeight: {
    description: &#x22;Screen height used with user agent parsing to derive device type.&#x22;,
    type: &#x22;number&#x22;,
  },
}"
/>

<Tabs items="['cURL', 'JavaScript']">
  <Tab value="cURL">
    ```bash
    curl -X POST "https://app.rybbit.io/api/sites/123/feature-flags/evaluate" \
      -H "Authorization: Bearer rb_your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "anonymousId": "visitor_abc",
        "identifiedUserId": "user_123",
        "hostname": "example.com",
        "pathname": "/checkout",
        "query": { "plan": "pro" },
        "language": "en-US",
        "screenWidth": 1440,
        "screenHeight": 900
      }'
    ```
  </Tab>

  <Tab value="JavaScript">
    ```javascript
    const response = await fetch(
      "https://app.rybbit.io/api/sites/123/feature-flags/evaluate",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer rb_your_api_key_here",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          anonymousId: "visitor_abc",
          identifiedUserId: "user_123",
          hostname: "example.com",
          pathname: "/checkout",
          query: { plan: "pro" },
          language: "en-US",
          screenWidth: 1440,
          screenHeight: 900,
        }),
      }
    );

    const data = await response.json();
    const newCheckout = data.flags.new_checkout?.value === true;
    ```
  </Tab>
</Tabs>

### Response [#response]

```json
{
  "flags": {
    "new_checkout": {
      "key": "new_checkout",
      "value": true,
      "flagType": "boolean",
      "payload": { "copy": "Try it now" },
      "conditionSet": "Default",
      "version": 3,
      "reason": "rollout",
      "matched": true,
      "rolloutPercentage": 100
    }
  },
  "generatedAt": "2026-05-27T12:00:00.000Z"
}
```

Assignment fields:

| Field               | Description                                                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`             | The evaluated flag value. Boolean flags return `true` or `false`; multiple variant flags return a variant key or `false`; remote config returns `true` when matched. |
| `payload`           | Optional payload from the selected condition set or selected variant.                                                                                                |
| `variant`           | Selected variant key for multiple variant flags.                                                                                                                     |
| `conditionSet`      | Name of the condition set that matched.                                                                                                                              |
| `reason`            | Why the assignment was produced, such as `rollout`, `variant`, `remote_config`, `fallthrough`, `target_mismatch`, or `disabled`.                                     |
| `matched`           | Whether the flag produced an active match.                                                                                                                           |
| `rolloutPercentage` | The rollout percentage that was evaluated.                                                                                                                           |
| `version`           | Flag version. Increments when the flag is edited.                                                                                                                    |

## Analytics and Filtering [#analytics-and-filtering]

Feature flag assignments are stored on events. Browser-tracked events include evaluated client flags automatically. Server-side events can include a `feature_flags` object in the [HTTP API](/docs/api/sending-events) payload:

```json
{
  "site_id": "123",
  "type": "custom_event",
  "event_name": "purchase",
  "pathname": "/checkout",
  "feature_flags": {
    "new_checkout": "true",
    "homepage_cta": "variant_a"
  }
}
```

Use feature flag filters in the dashboard to compare behavior between flag values.

## Best Practices [#best-practices]

* Keep flag keys stable and descriptive, such as `new_checkout` or `pricing_page_copy`.
* Use **Client** runtime only for values that are safe to expose in the browser.
* Use **Server** runtime for permission checks, pricing logic, and private backend behavior.
* Put specific condition sets before broad default condition sets.
* Keep remote config payloads small and JSON-serializable.
* Use a stable `anonymousId` for server-side evaluation so rollout assignments remain sticky.
* Remove stale flags after rollout is complete to keep your dashboard and codebase clean.

**Related Documentation:**

* [Tracking Script](/docs/script)
* [Identify Users](/docs/identify-users)
* [Tagging](/docs/tagging)
* [API - Sending Events](/docs/api/sending-events)


# Filter traffic (/de/docs/filter-traffic)





Rybbit provides server-side traffic filtering to keep unwanted data out of your analytics. You can exclude your own traffic, staging and preview environments, internal tools, monitoring checks, or entire countries.

Filters are configured from **Site Settings → Exclusions**.

## Available Filters [#available-filters]

| Filter                    | Use it for                                                            | Matching behavior                                         | Limit       |
| ------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- | ----------- |
| **IP Exclusions**         | Your home, office, VPN, or internal network traffic                   | Single IPs, CIDR ranges, and IPv4 ranges                  | 100 entries |
| **Country Exclusions**    | Regional filtering or compliance requirements                         | Two-letter ISO country codes, such as `US`, `GB`, or `DE` | 250 entries |
| **Path Exclusions**       | Admin pages, private pages, preview routes, or test pages             | Case-insensitive glob patterns using `*`                  | 100 entries |
| **Hostname Exclusions**   | Localhost, staging domains, preview deployments, or temporary domains | Case-insensitive glob patterns using `*`                  | 100 entries |
| **User Agent Exclusions** | Monitoring tools, headless browsers, or custom crawlers               | Case-insensitive substring matching                       | 100 entries |

When a request matches an exclusion, Rybbit returns a successful response but does not write the event to analytics storage.

## IP Exclusions [#ip-exclusions]

Block traffic from specific IP addresses or ranges at the server level. This is usually the best way to hide your own traffic.

Supported formats:

* **Single IPv4**: `192.168.1.1`
* **Single IPv6**: `2001:db8::1`
* **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`
* **IPv4 ranges**: `192.168.1.1-192.168.1.10`

For setup instructions and best practices, see [Hiding Your Own Traffic](/docs/hiding-own-traffic).

## Country Exclusions [#country-exclusions]

Block all traffic geolocated to specific countries. Rybbit resolves the visitor IP address with the MaxMind GeoLite2 database, then compares the resulting country code to your exclusion list.

Use two-letter ISO country codes:

* `US` for United States
* `GB` for United Kingdom
* `CN` for China
* `DE` for Germany

Country codes are stored as uppercase values in the dashboard and API.

<Callout type="warning">
  **Private IP addresses**: Country exclusion cannot work for private IP addresses such as `127.0.0.1`, `192.168.x.x`, `10.x.x.x`, or `172.16.x.x` because they cannot be geolocated. This includes localhost and Docker container IPs during local development.
</Callout>

<Callout type="info">
  **VPNs and proxies**: Visitors using VPNs or proxies are detected based on the VPN or proxy server location, not their physical location.
</Callout>

## Path Exclusions [#path-exclusions]

Exclude traffic to specific page paths. Path exclusions match the pathname only, not the query string.

Examples:

```txt
/admin/*
/preview
/internal/*
```

Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `/admin/*` matches `/admin/users` and `/admin/settings`.

Use path exclusions for pages that should not appear in analytics at all, such as admin dashboards, internal previews, or test routes.

<Callout type="info">
  For client-side-only pageview skipping, you can also use the tracking script's `data-skip-patterns` option. Site-level path exclusions are enforced on the server and also apply to session replay ingestion.
</Callout>

## Hostname Exclusions [#hostname-exclusions]

Exclude traffic from specific hostnames. This is useful when the same site ID is used across production, staging, preview, and local environments.

Examples:

```txt
localhost
staging.example.com
*.vercel.app
*.netlify.app
```

Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `*.vercel.app` matches `my-preview.vercel.app` but not `vercel.app`.

## User Agent Exclusions [#user-agent-exclusions]

Exclude traffic from requests whose user agent contains a configured substring.

Examples:

```txt
HeadlessChrome
MyMonitor
Pingdom
```

Matching is case-insensitive and uses substring matching, so `HeadlessChrome` matches `Mozilla/5.0 HeadlessChrome/120`.

Use user-agent exclusions for uptime monitors, synthetic checks, internal crawlers, or other tools with predictable user-agent strings.

## What Filters Apply To [#what-filters-apply-to]

Traffic filters run before normal analytics data is stored. They apply to:

* Pageviews
* Custom events
* Performance and Web Vitals events
* Error events
* Autocapture events
* Session replay batches

## How Filters Are Evaluated [#how-filters-are-evaluated]

Rybbit checks exclusions in this order:

1. IP address
2. Country
3. Path
4. Hostname
5. User agent

If any filter matches, the event is accepted with a `200` response but is not tracked. Changes usually take effect within 60 seconds because site configuration is cached briefly on the server.

## Testing Filters Locally [#testing-filters-locally]

To test country filtering locally, send a public IP through the `X-Real-IP` header:

```bash
curl -X POST http://localhost:3001/api/track \
  -H "Content-Type: application/json" \
  -H "X-Real-IP: 8.8.8.8" \
  -d '{
    "type": "pageview",
    "site_id": "your-site-id",
    "hostname": "example.com",
    "pathname": "/test"
  }'
```

For path and hostname filters, set `pathname` and `hostname` in the event payload to values that should match your configured exclusions.


# Funnels (/de/docs/funnels)













<img alt="Funnels Dashboard" src="__img0" />

Funnels let you define a sequence of steps — page visits, custom events, or autocaptured interactions — and measure how many users progress through each stage. You can see where users convert, where they drop off, and drill into the sessions at each step to understand why.

## Creating a Funnel [#creating-a-funnel]

<img alt="Creating a Funnel" src="__img1" />

<Steps>
  <Step>
    ### Click "Create Funnel" [#click-create-funnel]

    Each funnel has:

    * **Name** — A label for the funnel (e.g., "Signup Flow", "Checkout Process")
    * **Steps** — Two or more sequential steps, each tracking a page visit, custom event, outbound link, button click, form submission, or copy event
  </Step>

  <Step>
    ### Add Steps [#add-steps]

    A funnel always must have at least two steps.

    There are six types of funnel steps. Path and custom event steps require a value. For the four autocaptured interaction types, the pattern is optional—leave it empty to match every interaction of that type.

    <Tabs items="['Path', 'Custom Event', 'Outbound Link', 'Button Click', 'Form Submit', 'Copy']">
      <Tab value="Path">
        Path steps match pageview events by URL path.

        * Enter a URL path starting with `/`
        * Wildcards are supported:
          * `*` matches a single path segment — `/products/*` matches `/products/shoes`
          * `**` matches multiple segments — `/docs/**` matches `/docs/api/v2/intro`
      </Tab>

      <Tab value="Custom Event">
        Custom event steps match events by name (e.g., `add_to_cart`, `purchase_completed`).

        Events must be tracked using the Rybbit tracking script. See [Track Events](/docs/track-events) for setup instructions.
      </Tab>

      <Tab value="Outbound Link">
        Outbound link steps match clicks on links that lead away from your site.

        * Enter a destination URL pattern such as `https://example.com/pricing` or `https://*.example.com/**`
        * Leave the pattern empty to match any outbound click

        Outbound link tracking is enabled by default.
      </Tab>

      <Tab value="Button Click">
        Button click steps match clicks on buttons, button/submit inputs, and elements with `role="button"`.

        * Enter a visible button-text pattern such as `Sign Up` or `Start * Trial`
        * Leave the pattern empty to match any button click

        Buttons that already use `data-rybbit-event` are recorded as custom events instead.
      </Tab>

      <Tab value="Form Submit">
        Form submit steps match submissions of HTML forms.

        * Enter a form name or ID pattern such as `signup-form`
        * The pattern can also match the form's action URL
        * Leave the pattern empty to match any form submission
      </Tab>

      <Tab value="Copy">
        Copy steps match text that visitors copy from your site.

        * Enter a copied-text pattern such as `PROMO*`
        * Leave the pattern empty to match any copied text
      </Tab>
    </Tabs>

    Autocaptured interaction patterns support wildcards: `*` matches one or more characters and `**` also matches an empty value. The form suggests values already observed on your site.

    <Callout type="info" title="Enable autocapture first">
      Button click, form interaction, and copy tracking are disabled by default. Enable the event types you want to use in the **Tracking** tab of your site settings. Only interactions collected after tracking is enabled can appear in a funnel. See [Autocapture](/docs/autocapture) for the properties collected with each type.
    </Callout>
  </Step>

  <Step>
    ### Configure Step Options (optional) [#configure-step-options-optional]

        <img alt="Step Options" src="__img2" />

    Each step has additional configuration options:

    * **Label** (optional) — A friendly display name for the step
    * **Hostname** (optional) — Restrict matching to a specific domain, useful for multi-domain sites
    * **Property Filters** (optional) — Filter by URL parameters (for path steps) or event properties (for all other step types). Multiple filters can be added per step, and all must match.
  </Step>
</Steps>

## Reading Funnel Results [#reading-funnel-results]

The funnel visualization updates in real time as you configure steps. For each step, you'll see:

* **Sessions** — How many sessions reached this step
* **Conversion Rate** — Percentage of the first step's sessions that reached this step
* **Dropped** — How many sessions completed the previous step but not this one
* **Dropoff Rate** — Percentage of the previous step's sessions lost at this point

The horizontal bar for each step shows two layers:

* **Solid bar** — Overall conversion from the first step
* **Striped overlay** — Conversion from the immediately previous step

Steps are evaluated sequentially — each step must occur after the previous one within the same session.

## Viewing Sessions [#viewing-sessions]

<img alt="Viewing Sessions" src="__img3" />

Click any step to expand it and view the sessions associated with that step:

* **Reached** tab — Sessions that completed this step
* **Dropped Off** tab — Sessions that reached the previous step but didn't make it to this one (available for step 2 and beyond)

Each session shows entry/exit pages, duration, location, device info, referrer, UTM parameters, and user ID if identified. Sessions are paginated.

***

**Related Documentation:**

* [Autocapture](/docs/autocapture) — Configure automatically captured interactions
* [Goals](/docs/goals) — Track single-action conversions
* [Track Events](/docs/track-events) — Set up custom event tracking


# Goals (/de/docs/goals)













<img alt="Goals Dashboard" src="__img0" />

Goals let you define specific actions — from visiting a page to clicking a button — and measure how often your visitors complete them. Each goal tracks a conversion rate against total sessions, giving you a clear picture of how effectively your site drives key outcomes.

## Creating a Goal [#creating-a-goal]

<img alt="Creating a Goal" src="__img1" />

<Steps>
  <Step>
    ### Click "Create Goal" [#click-create-goal]

    Every goal has:

    * **Name** (optional) — A friendly label like "Completed Checkout" or "Signed Up"
    * **Type** — Page, custom event, outbound link, button click, form submission, or copied text
    * **Value** — A required path or custom event name, or an optional pattern that narrows an autocaptured interaction
  </Step>

  <Step>
    ### Choose a Goal Type [#choose-a-goal-type]

    There are six goal types. Page and custom event goals require a value. For the four autocaptured interaction types, the pattern is optional—leave it empty to count every interaction of that type.

    <Tabs items="['Page', 'Custom Event', 'Outbound Link', 'Button Click', 'Form Submit', 'Copy']">
      <Tab value="Page">
        Page goals track when a user visits a URL matching a given path pattern.

        * The value must be a path starting with `/` (not a full URL)
        * Wildcards are supported:
          * `*` matches a single path segment — `/blog/*` matches `/blog/my-post`
          * `**` matches multiple segments — `/docs/**` matches `/docs/api/v2/intro`

        The form provides autocomplete suggestions based on actual paths seen on your site.
      </Tab>

      <Tab value="Custom Event">
        Custom event goals track when an event with a specific name is fired. The value is the event name (e.g., `signup_clicked`, `purchase_completed`).

        Events must be tracked using the Rybbit tracking script. See [Track Events](/docs/track-events) for setup instructions.
      </Tab>

      <Tab value="Outbound Link">
        Outbound link goals track clicks on links that lead away from your site.

        * Enter a destination URL pattern such as `https://example.com/pricing` or `https://*.example.com/**`
        * Leave the pattern empty to count clicks to any external URL

        Outbound link tracking is enabled by default.
      </Tab>

      <Tab value="Button Click">
        Button click goals track clicks on buttons, button/submit inputs, and elements with `role="button"`.

        * Enter a visible button-text pattern such as `Sign Up` or `Start * Trial`
        * Leave the pattern empty to count any button click

        Buttons that already use `data-rybbit-event` are recorded as custom events instead.
      </Tab>

      <Tab value="Form Submit">
        Form submit goals track submissions of HTML forms.

        * Enter a form name or ID pattern such as `signup-form`
        * The pattern can also match the form's action URL
        * Leave the pattern empty to count any form submission
      </Tab>

      <Tab value="Copy">
        Copy goals track text that visitors copy from your site.

        * Enter a copied-text pattern such as `PROMO*`
        * Leave the pattern empty to count any copied text
      </Tab>
    </Tabs>

    Autocaptured interaction patterns support wildcards: `*` matches one or more characters and `**` also matches an empty value. The form suggests values already observed on your site.

    <Callout type="info" title="Enable autocapture first">
      Button click, form interaction, and copy tracking are disabled by default. Enable the event types you want to use in the **Tracking** tab of your site settings. Only interactions collected after tracking is enabled can count toward a goal. See [Autocapture](/docs/autocapture) for the properties collected with each type.
    </Callout>
  </Step>

  <Step>
    ### Add Property Filters (optional) [#add-property-filters-optional]

        <img alt="Property Filters" src="__img2" />

    You can narrow a goal to only count conversions when specific properties match:

    * **Page goals** — Filter by URL parameters (e.g., only count visits where `utm_source=adwords`)
    * **Custom event goals** — Filter by event properties (e.g., only count events where `plan=premium`)
    * **Autocaptured interaction goals** — Filter by captured properties such as `url`, `text`, `formName`, `formId`, or `formAction`

    Toggle **Match specific URL parameters** or **Match specific event properties** to add filters. You can add multiple filters per goal — all filters must match for a session to count as a conversion.
  </Step>
</Steps>

## Goal Metrics [#goal-metrics]

Each goal card displays:

* **Total Conversions** — The number of distinct sessions that completed the goal
* **Conversion Rate** — Conversions divided by total sessions in the selected time period, shown as a percentage with a visual progress bar

Goals respect the global date range and filters (country, device, browser, etc.) applied on the page.

## Viewing Converted Sessions [#viewing-converted-sessions]

<img alt="Viewing Converted Sessions" src="__img3" />

Click a goal card to expand it and see the sessions that converted. Each session shows:

* Entry and exit pages
* Session duration
* Location (country, region, city)
* Device, browser, and OS
* Referrer, channel, and UTM parameters
* User ID (if identified)

Sessions are sorted by most recent first and paginated.

***

**Related Documentation:**

* [Autocapture](/docs/autocapture) — Configure automatically captured interactions
* [Track Events](/docs/track-events) — Set up custom event tracking
* [Funnels](/docs/funnels) — Analyze multi-step conversion paths


# Hiding your own traffic (/de/docs/hiding-own-traffic)





There are several ways to disable Rybbit tracking to hide your own visits from analytics.

<Tabs items="['IP Exclusion', 'Browser Extensions', 'localStorage Method']">
  <Tab>
    **IP Exclusion (Recommended)**: Block traffic from specific IP addresses or ranges at the server level for complete accuracy.

    ### Setting Up IP Exclusion [#setting-up-ip-exclusion]

    1. **Navigate to Site Settings**: Go to your site's settings page in the Rybbit dashboard
    2. **Find IP Exclusions section**: Scroll down to the "IP Exclusions" configuration
    3. **Add your IP addresses**: Enter the IP addresses or ranges you want to exclude

    ### Supported IP Formats [#supported-ip-formats]

    Rybbit supports multiple IP exclusion formats:

    * **Single IPv4**: `192.168.1.1`
    * **Single IPv6**: `2001:db8::1`, `::1`
    * **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`
    * **IPv4 ranges**: `192.168.1.1-192.168.1.10` (IPv4 only)

    ### Examples [#examples]

    ```
    # Your home IP address
    203.0.113.45

    # Your office network (CIDR)
    203.0.113.0/24

    # IP range for your team
    198.51.100.10-198.51.100.20

    # IPv6 address
    2001:db8::1
    ```

    ### Key Features [#key-features]

    * **Server-side filtering**: Traffic is blocked before it reaches your analytics, providing highly accurate exclusion
    * **Multiple formats**: Supports individual IPs, CIDR notation, and ranges
    * **IPv4 and IPv6**: Full support for both IP versions
    * **Near real-time updates**: Changes take effect within seconds
    * **No browser dependency**: Works regardless of browser or device

    <Callout type="info">
      **IP Stability Note**: IP addresses can change due to factors like mobile networks, VPN usage, ISP changes, and IPv6 privacy extensions. You may need to periodically update your excluded IPs to maintain effective filtering.
    </Callout>

    <Callout type="info">
      **Dynamic IP Addresses**: If you frequently use VPNs, mobile networks, or have a dynamic IP address that changes regularly, consider these approaches:

      * Use CIDR ranges that cover your typical IP pool (consult your ISP or VPN provider)
      * Combine IP exclusion with browser extensions for comprehensive coverage
      * Check your current IP periodically and update exclusions as needed
      * For corporate networks, exclude the entire office IP range rather than individual addresses
    </Callout>

    <Callout type="warning">
      **Note**: IPv6 range notation (e.g., `2001:db8::1-2001:db8::ff`) is not supported. Use CIDR notation instead (e.g., `2001:db8::/32`).
    </Callout>

    <Callout type="info">
      **Finding your IP**: You can find your current IP address by visiting sites like [whatismyipaddress.com](https://whatismyipaddress.com) or [ipinfo.io](https://ipinfo.io).
    </Callout>
  </Tab>

  <Tab>
    **Browser Extensions**: Easy client-side solution using community-maintained browser extensions.

    ### Available Extensions [#available-extensions]

    * **[Chrome Extension](https://chrome.google.com/webstore/detail/gofnfdfidbkpellionhpmkejgaajieoo)**: Install from the Chrome Web Store
    * **[Firefox Extension](https://addons.mozilla.org/en-US/firefox/addon/rybbit-opt-out/)**: Install from Firefox Add-ons

    These extensions automatically disable Rybbit tracking on all websites where you have Rybbit installed, without requiring any manual configuration.

    <Callout type="info">
      **Self-hosted users**: These extensions require Rybbit version 1.1.0 or higher. If you're running an older version, please update your installation or use the localStorage method.
    </Callout>

    *These extensions are community-maintained by [@davidfiala](https://github.com/davidfiala).*
  </Tab>

  <Tab>
    **localStorage Method**: Manual configuration using your browser's developer console for more granular control.

    <Steps>
      ### 1. Open your browser's developer console [#1-open-your-browsers-developer-console]

      Press **F12** or right-click the page and select "Inspect"

      Navigate to the "Console" tab

      ### 2. Disable tracking [#2-disable-tracking]

      Enter this command to disable tracking:

      ```js
      localStorage.setItem('disable-rybbit', 'true');
      ```

      ### 3. Re-enable tracking (when needed) [#3-re-enable-tracking-when-needed]

      If you want to re-enable tracking later, enter:

      ```js
      localStorage.removeItem('disable-rybbit');
      ```
    </Steps>
  </Tab>
</Tabs>

## Summary [#summary]

Multiple methods are available for hiding your own traffic, each with different advantages:

* **IP exclusion** provides the most accurate solution by blocking traffic at the server level, working regardless of browser or device
* **Browser extensions** offer convenience by automatically working across all your Rybbit-enabled websites
* **localStorage method** gives granular control for specific websites or temporary disabling

For most users, **IP exclusion is recommended** as it provides highly accurate filtering for all devices accessing your site from the excluded IP addresses. The other methods work at the browser level and may be useful for additional flexibility or temporary exclusions.


# Identify Users (/de/docs/identify-users)





<Callout type="warn" title="GDPR & Privacy Compliance">
  User identification involves processing personal data. Before using these features, ensure you have a lawful basis for processing (typically user consent), have disclosed tracking in your privacy policy, and provide users the ability to access and delete their data. Only collect traits you have explicit consent to process.
</Callout>

Rybbit allows you to identify logged-in users and associate their activity with a persistent identity across devices and sessions. This enables powerful user-level analytics, including tracking user journeys, understanding retention, and personalizing experiences.

<img alt="identify users" src="__img0" />

## How It Works [#how-it-works]

By default, Rybbit assigns an anonymous ID to each visitor based on their device fingerprint. When you call `identify()`, you link this anonymous visitor to a known user ID, allowing you to:

* Track the same user across multiple devices
* Associate pre-login activity with the logged-in user
* Store user metadata (traits) like email, name, and custom fields
* View identified users in your dashboard with their real names

When a new alias is created (i.e., the first time `identify()` is called for a given device), Rybbit retroactively updates all past anonymous events from that device to include the identified user ID. This means pre-login pageviews and events are attributed to the user once they identify themselves.

## Special Trait Fields [#special-trait-fields]

When identifying users, certain trait fields are treated specially by Rybbit:

| Field      | Description                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| `username` | **Primary display name** - Shown in the users list and session cards instead of the user ID |
| `name`     | **Fallback display name** - Used if username is not provided                                |
| `email`    | Displayed below the user's name in the dashboard                                            |

You can also include any custom fields you need for segmentation and analysis.

## Limits [#limits]

* **Traits size**: Maximum 2KB per identify call. Traits are stored as JSON, so keep payloads concise.
* **User ID length**: Maximum 255 characters.

## API Reference [#api-reference]

### `window.rybbit.identify(userId, traits?)` [#windowrybbitidentifyuserid-traits]

Sets a custom user ID for tracking logged-in users across devices and sessions, with optional user traits (metadata).

* `userId` (String): The unique identifier for the user. This will be stored in localStorage and persist across browser sessions. &#x2A;*Note: Custom user IDs are stored exactly as provided without any hashing or modification.**
* `traits` (Object, Optional): An object containing user metadata like email, name, username, or any custom fields. This data is stored in Rybbit and can be used to identify users in the dashboard. Setting a trait to `null` removes it from the user's profile.

```javascript
// Identify a user when they log in (without traits)
window.rybbit.identify("user_12345");

// Identify a user with traits (recommended)
window.rybbit.identify("user_12345", {
  username: "johndoe",           // Primary display name
  name: "John Doe",              // Fallback display name
  email: "john@example.com",
  plan: "premium",
  company: "Acme Inc"
});

// All subsequent events and pageviews will be associated with this user ID
```

### `window.rybbit.setTraits(traits)` [#windowrybbitsettraitstraits]

Updates the traits for the currently identified user without re-identifying them. Useful for updating user properties after initial identification.

* `traits` (Object): An object containing user metadata. New traits are merged with existing traits. &#x2A;*Setting a trait to `null` removes it from the user's profile.**

```javascript
// Update user traits after they upgrade their plan
window.rybbit.setTraits({
  plan: "enterprise",
  upgraded_at: "2024-01-15"
});

// Remove a trait by setting it to null
window.rybbit.setTraits({
  temporary_flag: null  // This trait will be removed
});
```

**Note:** You must call `identify()` before using `setTraits()`. If no user is identified, this will log a warning.

### `window.rybbit.clearUserId()` [#windowrybbitclearuserid]

Clears the stored user ID. Useful when a user logs out.

```javascript
// Clear user identification when user logs out
window.rybbit.clearUserId();
```

### `window.rybbit.getUserId()` [#windowrybbitgetuserid]

Returns the currently set user ID, or `null` if none is set.

```javascript
// Check if a user is identified
const currentUserId = window.rybbit.getUserId();
if (currentUserId) {
  console.log('Current user:', currentUserId);
} else {
  console.log('No user identified');
}
```

## Important Notes [#important-notes]

* **Unique user counts**: Every user count in the dashboard — Unique Users, the users chart, the Users table, traits, and retention — keys on the custom user ID wherever one is present, falling back to the anonymous fingerprint only for visitors who have never identified. Two people sharing an IP address and browser count as two users, and one person on a laptop and a phone counts as one. Sites that never call `identify()` are unaffected. Because the count follows the IDs you pass, sending a fresh ID per visit (rather than a stable per-person ID) will inflate it.
* **Identified sessions**: When a custom user ID is present, session assignment includes both the anonymous device fingerprint and the custom user ID. Different identified users therefore remain in separate sessions even when they share the same IP address and user agent.
* **Shared devices**: If multiple users log in from the same device (same IP address and user agent), calling `identify()` with a new user ID updates the alias to point to the new user. Future events will be attributed to the most recently identified user. Past events that were already backfilled retain their original attribution.
* **Cross-device tracking**: Identifying the same user on different devices creates separate aliases. Events from each device are linked to the user independently via the `identified_user_id` field.
* **Retroactive backfill**: The backfill runs asynchronously when a new alias is first created. ClickHouse mutations may take a short time to propagate depending on table size. Subsequent `identify()` calls from the same device (even with a different user ID) do not re-backfill old events.
* **`clearUserId()` behavior**: Calling `clearUserId()` removes the user ID from localStorage so future events are anonymous. It does not delete the alias in the database or modify previously attributed events.

## Complete Example [#complete-example]

Here's a typical workflow for user identification:

```javascript
// When user logs in
function handleLogin(userData) {
  // Set user identification with traits
  window.rybbit.identify(userData.id, {
    username: userData.username,
    name: userData.fullName,
    email: userData.email,
    plan: userData.plan
  });

  // Track login event
  window.rybbit.event("User Login", {
    method: "email"
  });
}

// When user upgrades their plan
function handlePlanUpgrade(newPlan) {
  // Update traits without re-identifying
  window.rybbit.setTraits({
    plan: newPlan,
    upgraded_at: new Date().toISOString()
  });

  // Track upgrade event
  window.rybbit.event("Plan Upgraded", {
    new_plan: newPlan
  });
}

// When user logs out
function handleLogout() {
  // Track logout event
  window.rybbit.event("User Logout");

  // Clear user identification
  window.rybbit.clearUserId();
}

// Check identification status
function checkUserStatus() {
  const userId = window.rybbit.getUserId();
  if (userId) {
    console.log("User is identified:", userId);
  } else {
    console.log("Anonymous user");
  }
}
```

**Related Documentation:**

* [Track Events](/docs/track-events)
* [Behavior Analytics - Users Tab](/docs/behavior-analytics/users)
* [API - Sending Events](/docs/api/sending-events)


# Introduction (/de/docs)



**Rybbit** is a powerful open source web and product analytics platform. Check out our [live demo](https://demo.rybbit.com/81) using a real production site.

<DocsHomeCards />

## Getting Started [#getting-started]

Choose the option that's right for you:

* **Cloud Version:** Sign up for the [hosted version](https://app.rybbit.io/signup). Get up and running in minutes.
* **Self-Host:** Follow our [self hosting guide](/docs/self-hosting) to set up Rybbit on your own server.

And then learn how to add the [tracking script](/docs/script) to your website to start collecting data.

## Code [#code]

Rybbit is open sourced under the AGPL-3.0 license. You can find the code on [GitHub](https://github.com/rybbit-io/rybbit).

## Community [#community]

Join our [Discord server](https://discord.gg/DEhGb4hYBj) or talk to me on [X](https://x.com/yang_frog). I'm always looking for feedback and ideas to make Rybbit as awesome as possible.


# Inviting users (/de/docs/inviting-users)





<Callout type="info">
  On self-hosted instances, this workflow is slightly different. Instead of inviting users, you can create a new user and set their password directly since self-hosted instances don't send emails.
</Callout>

<Steps>
  <Step>
    ### Add the user to your organization [#add-the-user-to-your-organization]

    Go to **Settings > Organization** and click the "Invite Member" button. Enter the user's email address.
  </Step>

  <Step>
    ### Select the user's role [#select-the-users-role]

    You can assign the user one of three roles:

    **Owners** have full access to all features including billing, organization deletion, and member management.

    **Admins** can manage members and access all sites, but cannot delete the organization or manage billing.

    **Members** can view analytics for assigned sites only. They cannot manage settings or other members.

    #### Restricting site access for members [#restricting-site-access-for-members]

    When inviting a member, you can optionally restrict their access to specific sites. Check the "Restrict access to specific sites" option and select which sites the member should be able to view.

    If you don't enable this option, the member will have access to all sites in your organization.

    <Callout type="info">
      Site access restrictions only apply to members. Admins and owners always have full access to all sites.
    </Callout>
  </Step>

  <Step>
    ### Assign teams (optional) [#assign-teams-optional]

    If your organization has [teams](/docs/teams) set up, you can assign the new member to a team during the invitation. When the member accepts the invitation, they will automatically be added to the selected team.

    This is useful for ensuring new members immediately have access to the right group of sites without needing to configure access separately.
  </Step>

  <Step>
    ### Send the invite [#send-the-invite]

    Click the "Invite" button. The user will receive an email with a link to sign up for Rybbit. You can manage all pending invitations in the Organization settings page.
  </Step>
</Steps>

## Managing site access for existing members [#managing-site-access-for-existing-members]

You can change a member's site access at any time after they've joined your organization.

1. Go to **Settings > Organization**
2. Find the member in the list and click the edit (pencil) icon in the Actions column for that member
3. Toggle "Restrict access to specific sites" and select the sites they should have access to
4. Click "Save changes"

The member will immediately only see the sites you've selected. If you disable the restriction, they'll regain access to all sites.

<Callout type="info">
  Currently, each user can only be in one organization.
</Callout>


# Localhost tracking (/de/docs/localhost-tracking)





Rybbit does not restrict tracking to your registered domain — the tracking script works from `localhost` (or any other origin) out of the box. As long as your snippet has a valid `data-site-id`, events sent during local development are recorded like any other traffic.

```html
<script
  defer
  src="https://app.rybbit.io/api/script.js"
  data-site-id="YOUR_SITE_ID">
</script>
```

<Callout type="warning">
  Because localhost traffic is tracked by default, the usual problem is the opposite one: development visits polluting your production analytics. Use one of the approaches below to keep your data clean.
</Callout>

## Keeping development traffic out of production data [#keeping-development-traffic-out-of-production-data]

### Option 1: Use a separate development site [#option-1-use-a-separate-development-site]

Create a second site in your Rybbit dashboard (e.g. "My App (dev)") and use its site ID during development. Your production site's data stays untouched, and you can still verify events end-to-end.

```jsx
// Next.js example
export function Analytics() {
  const siteId =
    process.env.NODE_ENV === 'development'
      ? process.env.NEXT_PUBLIC_RYBBIT_DEV_SITE_ID
      : process.env.NEXT_PUBLIC_RYBBIT_SITE_ID;

  return (
    <script
      defer
      src="https://app.rybbit.io/api/script.js"
      data-site-id={siteId}
    />
  );
}
```

### Option 2: Only load the script in production [#option-2-only-load-the-script-in-production]

If you don't need analytics while developing, skip loading the script entirely outside production:

```jsx
// Next.js example
export function Analytics() {
  if (process.env.NODE_ENV !== 'production') return null;

  return (
    <script
      defer
      src="https://app.rybbit.io/api/script.js"
      data-site-id={process.env.NEXT_PUBLIC_RYBBIT_SITE_ID}
    />
  );
}
```

```javascript
// Vanilla JS example
if (process.env.NODE_ENV === 'production') {
  const script = document.createElement('script');
  script.defer = true;
  script.src = 'https://app.rybbit.io/api/script.js';
  script.setAttribute('data-site-id', 'YOUR_SITE_ID');
  document.head.appendChild(script);
}
```

### Option 3: Filter the traffic instead [#option-3-filter-the-traffic-instead]

If you want the script loaded everywhere but excluded from your stats, use your site's exclusion settings — see [Filtering Traffic](/docs/filter-traffic) and [Hiding Your Own Traffic](/docs/hiding-own-traffic).

## Troubleshooting [#troubleshooting]

**Events not showing up from localhost?**

* Confirm `data-site-id` matches the site you're looking at in the dashboard
* Check the browser console for errors and the Network tab for `POST` requests to `/api/track`
* Disable ad blockers or privacy extensions — they commonly block analytics scripts on any origin, including localhost
* Make sure the page isn't excluded by your site's IP, path, or user-agent exclusion rules


# Managing your installation (/de/docs/managing-your-installation)





## Helpful scripts [#helpful-scripts]

<Callout>
  You probably need to run `chmod +x *.sh` before running the scripts.
</Callout>

### Updating Your Installation [#updating-your-installation]

Rybbit is updated frequently with new features and bug fixes. You can update your installation by running the following commands:

**update.sh**: Update to the latest version by pulling new code and rebuilding containers

```bash
git pull
./update.sh
```

### Restarting Your Installation [#restarting-your-installation]

**restart.sh**: Restart all services (useful when you've changed .env settings)

```bash
./restart.sh
```

## Docker Compose Commands [#docker-compose-commands]

You can also manage services directly with Docker Compose:

* **Stop all services**:
  ```bash
  docker compose stop
  ```

* **Stop and remove containers** (preserves data):
  ```bash
  docker compose down
  ```

* **Start services** (if you used setup.sh with default webserver):
  ```bash
  docker compose --profile with-webserver up -d
  ```

* **Start services** (if you used setup.sh with --no-webserver):
  ```bash
  docker compose up -d
  ```

* **View logs**:
  ```bash
  docker compose logs -f
  ```

<Callout>
  If you are using your self-hosted Rybbit without anyone else, you can disable new user signups by setting `DISABLE_SIGNUP=true` in the `.env` file at the root of the repository.
</Callout>

## Database Access [#database-access]

You can access the databases by running the following commands:

* **Access Clickhouse**:
  ```bash
  docker exec -it clickhouse clickhouse-client --database analytics
  ```

* **Access Postgres**:
  ```bash
  docker exec -it postgres psql -U frog -d analytics
  ```

### Edit Session Replay Retention Policy [#edit-session-replay-retention-policy]

The default session replay retention policy is 30 days. This may be too long for some users as session replays can take up a lot of space. You can edit it by running the following command:

```bash
docker exec -it clickhouse clickhouse-client --database analytics
ALTER TABLE session_replay_events MODIFY TTL toDateTime(timestamp) + INTERVAL 14 DAY;
ALTER TABLE session_replay_metadata MODIFY TTL start_time + INTERVAL 14 DAY;
```

## Anonymous Usage Telemetry [#anonymous-usage-telemetry]

To help us improve Rybbit, self-hosted instances automatically send anonymous usage statistics to our cloud service. This includes:

* Number of rows in a few core ClickHouse tables (events and the session replay tables)
* Total database size
* Your Rybbit version
* A hashed instance identifier

No personal data, website content, or visitor information is ever collected.

<Callout type="info">
  You can completely disable telemetry by adding `DISABLE_TELEMETRY=true` to your `.env` file and restarting your services.
</Callout>


# Organization settings (/de/docs/organization-settings)







Access organization settings by clicking on "Organization" or going to [app.rybbit.io/settings/organization](https://app.rybbit.io/settings/organization).

<img alt="organization settings" src="__img0" />

## Organization [#organization]

### Organization Name [#organization-name]

Update your organization's display name. Only the organization owner can change this setting.

### Delete Organization [#delete-organization]

Permanently delete the organization and all associated data including sites, analytics, reports, and member associations.

<Callout type="warn">
  This action cannot be undone. You must type the organization name to confirm deletion. If you have an active subscription, you must cancel it before deleting the organization.
</Callout>

## Members [#members]

View and manage all members in your organization. The members table shows:

* **Name** - Member's display name
* **Email** - Member's email address
* **Role** - Owner, Admin, or Member
* **Site Access** - Which sites the member can access
* **Joined** - When they joined the organization

### Member Roles [#member-roles]

| Role       | Permissions                                                                               |
| ---------- | ----------------------------------------------------------------------------------------- |
| **Owner**  | Full access to all features, can manage members, billing, and delete the organization     |
| **Admin**  | Can manage members and access all sites, cannot delete the organization or manage billing |
| **Member** | Can view analytics for assigned sites only, cannot manage settings or other members       |

### Inviting Members [#inviting-members]

Owners can invite new members or create user accounts. See the [Inviting Users](/docs/inviting-users) guide for detailed instructions.

### Teams [#teams]

You can organize sites into teams to control which members have access to which sites. See the [Teams](/docs/teams) guide for details.


# Roadmap (/de/docs/roadmap)



Rybbit is a quickly growing project. We already have quite a few features, but there is much more to come.

## Planned features [#planned-features]

* Data import from Google Analytics, PostHog, and more
* More tracking script/SDK integration guides
* Custom themes

Once again, join our [Discord server](https://discord.gg/DEhGb4hYBj) or follow me on [X](https://x.com/yang_frog) to share your feedback and ideas. We would love to hear from you!


# Troubleshooting (/de/docs/script-troubleshooting)





If you've installed the Rybbit tracking script but aren't seeing any traffic in your dashboard, this guide will help you diagnose and fix common issues.

## Check if the Script is Loaded [#check-if-the-script-is-loaded]

The first step is to verify that the Rybbit script is properly loaded on your page.

<Steps>
  <Step>
    ### Open Your Browser's Developer Console [#open-your-browsers-developer-console]

    Right-click anywhere on your webpage and select **Inspect** (or **Inspect Element**). Then click on the **Console** tab at the top of the panel that opens.

    Alternatively, you can use keyboard shortcuts:

    * **Windows/Linux**: Press `Ctrl + Shift + J` or `F12`
    * **Mac**: Press `Cmd + Option + J`
  </Step>

  <Step>
    ### Type "rybbit" and Press Enter [#type-rybbit-and-press-enter]

    In the console, type `rybbit` and press Enter.

    **If the script is loaded correctly**, you'll see an object with functions like this:

    ```javascript
    {event: ƒ, pageview: ƒ, identify: ƒ, setTraits: ƒ, clearUserId: ƒ, …}
    ```

    **If the script is NOT loaded**, you'll see an error like:

    ```
    Uncaught ReferenceError: rybbit is not defined
    ```

    If you see the error, the script is not loading properly. Continue reading for common causes.
  </Step>
</Steps>

## Common Issues [#common-issues]

### Data Attributes Being Stripped [#data-attributes-being-stripped]

Some platforms, content management systems, tag managers, and "delay JavaScript" optimizers automatically remove or sanitize `data-*` attributes from script tags, or rebuild the tag from a `data-src` placeholder and drop everything else. If your site ID was in a `data-site-id` attribute, it gets removed and the script logs `Please provide a valid site ID`.

**Platforms known to strip attributes:**

* Google Tag Manager
* WordPress optimization plugins with "delay JavaScript" enabled (WP Rocket, Perfmatters, FlyingPress, LiteSpeed Cache)
* Some WordPress page builders
* Certain website builders (Webflow, Wix, Squarespace in some configurations)
* Some CDN or caching plugins

**Solution:** Put the site ID in the script URL instead of a data attribute. Optimizers preserve the URL:

```html
<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
```

If your platform also rewrites the `src`, inject the script from JavaScript instead:

```javascript
<script>
  (function() {
    var el = document.createElement("script");
    el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
    el.defer = true;
    document.head.appendChild(el);
  })();
</script>
```

<Callout type="info">
  For detailed Google Tag Manager setup instructions, see our [Google Tag Manager Guide](/docs/guides/google-tag-manager).
</Callout>

### Ad Blockers [#ad-blockers]

In rare cases, ad blockers may block the Rybbit tracking script. While Rybbit is privacy-focused and doesn't use cookies for tracking, some aggressive ad blockers may still flag analytics scripts.

**How to check if an ad blocker is the issue:**

1. Temporarily disable your ad blocker
2. Refresh the page
3. Check the console again for the `rybbit` object

**Solutions:**

* **For your own testing**: Disable your ad blocker or add your site to the allowlist
* **For your visitors**: Consider setting up a [proxy](/docs/proxy-guide) to serve the script from your own domain, which significantly reduces the chance of being blocked

### Script Not in the Right Location [#script-not-in-the-right-location]

The Rybbit script should be placed in the `<head>` section of your HTML. If it's placed in the wrong location or loaded after the page has already finished loading, it may not work correctly.

**Verify the script placement:**

1. View your page source (right-click → **View Page Source**)
2. Search for `rybbit` or `script.js`
3. Confirm it appears within the `<head>...</head>` tags

### Incorrect Site ID [#incorrect-site-id]

Double-check that the `siteId` in your script URL (or your `data-site-id` attribute) matches the site ID shown in your Rybbit dashboard.

1. Go to your Rybbit dashboard
2. Navigate to your site's settings
3. Copy the site ID and compare it with what's in your script tag

### Content Security Policy (CSP) Blocking [#content-security-policy-csp-blocking]

If your site has a strict Content Security Policy, it may block the Rybbit script from loading or executing.

**Check for CSP errors:**

1. Open the browser console
2. Look for errors mentioning "Content Security Policy" or "CSP"

**Solution:** Add the Rybbit script domain to your CSP headers:

```
script-src 'self' https://app.rybbit.io;
connect-src 'self' https://app.rybbit.io;
```

If you're self-hosting Rybbit, replace `app.rybbit.io` with your Rybbit instance domain.

### Script Loading Too Late in SPAs [#script-loading-too-late-in-spas]

In single-page applications (React, Vue, Next.js, etc.), if the script loads after the initial page render, the automatic pageview might not fire.

**Solution:** Ensure the script is in your root HTML template (like `index.html` or `_document.js` in Next.js), not dynamically imported in a component.

For Next.js specifically, see our [Next.js Guide](/docs/guides/nextjs).

## Testing Your Installation [#testing-your-installation]

Once you've made changes, verify that tracking is working:

1. **Check the console**: Type `rybbit` to confirm the object exists
2. **Trigger a test event**: In the console, run:
   ```javascript
   rybbit.event("test_event")
   ```
3. **Check your dashboard**: Navigate to the Events tab in your Rybbit dashboard and look for "test\_event" (it may take a few seconds to appear)
4. **Check the Network tab**: In browser dev tools, go to the Network tab, filter by "track" or "rybbit", and verify requests are being sent with 200 status codes

## Still Having Issues? [#still-having-issues]

If you've tried all the above and are still not seeing traffic:

1. **Check the browser Network tab** for any failed requests to your Rybbit instance
2. **Verify your site ID** is correct in the dashboard
3. **Check if traffic is being filtered** - review your [IP exclusions](/docs/hiding-own-traffic) and [country exclusions](/docs/filter-traffic) to ensure your traffic isn't being blocked
4. **For self-hosted instances** - ensure your Rybbit server is running and accessible

***

**Related Documentation:**

* [Tracking Script Installation](/docs/script)
* [Track Events](/docs/track-events)
* [Proxy Guide](/docs/proxy-guide)
* [Google Tag Manager Guide](/docs/guides/google-tag-manager)
* [Hide Your Own Traffic](/docs/hiding-own-traffic)
* [Filter Traffic](/docs/filter-traffic)


# Tracking script (/de/docs/script)





To start tracking user activity on your website, add the Rybbit tracking script to your site's HTML.

## Installation [#installation]

The webpage should give you this script tag like this when you first add a website. Place it within the `<head>` section of your website. Include it on every page you wish to track.

```html
<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" async></script>
```

If you are self-hosting Rybbit `app.rybbit.io` will be domain of your Rybbit instance.

The site ID is passed in the script URL. The older `data-site-id="YOUR_SITE_ID"` attribute still works, but the URL form is recommended because script optimizers (WP Rocket, Perfmatters, FlyingPress and similar "delay JavaScript" features) rebuild script tags and drop `data-*` attributes, while leaving the URL intact.

<Callout type="info">
  **Bypass Ad Blockers**: Some ad blockers may block analytics scripts regardless of privacy compliance. To improve tracking accuracy, you can proxy the tracking script through your own domain. See our [Proxy Guide](/docs/proxy-guide) for setup instructions for Next.js, Nginx, Caddy, and more.
</Callout>

## Configuration [#configuration]

### Site Settings Configuration [#site-settings-configuration]

Most tracking options are configured through your site settings in the Rybbit dashboard. The script automatically fetches these settings when it loads:

* **Automatic Initial Pageview**: Track the first pageview when the script loads
* **SPA Navigation**: Automatically track navigation in single-page applications
* **URL Parameters**: Include or exclude query strings from tracked URLs
* **Outbound Links**: Track clicks to external websites
* **Error Tracking**: Capture JavaScript errors and unhandled promise rejections
* **Session Replay**: Record user interactions for debugging and UX analysis
* **Web Vitals**: Collect Core Web Vitals performance metrics

### Script Attributes [#script-attributes]

These are the attributes you can pass to the script tag.

| Attribute            | Type     | Default | Description                                                                                                                                                                                                                                                                        |
| :------------------- | :------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-skip-patterns` | `string` | `[]`    | A JSON string array of URL path patterns to ignore. Pageviews matching these patterns won't be tracked. Supports two types of wildcards: `*` (matches within a segment) and `**` (matches across segments), plus regex patterns prefixed with `re:`.                               |
| `data-mask-patterns` | `string` | `[]`    | A JSON string array of URL path patterns to mask for privacy. Pageviews matching these patterns will be tracked, but the actual URL path will be replaced with the pattern itself in analytics data. Supports the same wildcards and `re:` regex patterns as `data-skip-patterns`. |
| `data-debounce`      | `string` | `"500"` | The delay (in milliseconds) before tracking a pageview after URL changes via the History API (`pushState`, `replaceState`). Set to `0` to disable debouncing.                                                                                                                      |
| `data-tag`           | `string` | `""`    | A label applied to all events from this script instance. Useful for A/B testing, deploy versioning, or cohort segmentation. Max 256 characters. See [Tagging](/docs/tagging).                                                                                                      |

{/* ### Feature Flags

  The tracking script automatically evaluates client and both-runtime feature flags when it loads. Read evaluated flags from `window.rybbit` after the script is ready:

  ```javascript
  window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);
  const config = rybbit.flagPayload("checkout_config", {});
  });
  ```

  Available methods:

  | Method | Description |
  | --- | --- |
  | `flag(key, fallback)` | Returns a boolean, variant key, or fallback value. Also records a feature flag exposure once per flag value/version. |
  | `flagPayload(key, fallback)` | Returns the payload for a flag, variant, or remote config. |
  | `flags()` | Returns all evaluated flag values. |
  | `flagPayloads()` | Returns all available flag payloads. |

  See [Feature Flags](/docs/feature-flags) for targeting rules, remote config, and server-side evaluation. */}

### Session Replay Attributes [#session-replay-attributes]

These attributes configure rrweb session replay behavior. They only apply when session replay is enabled in your site settings.

| Attribute                         | Type          | Default                          | Description                                                                                                                   |
| :-------------------------------- | :------------ | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `data-replay-mask-text-selectors` | `string`      | `[]`                             | A JSON string array of CSS selectors for elements whose text content should be masked. Example: `'[".user-name", "#email"]'`. |
| `data-replay-block-class`         | `string`      | `"rr-block"`                     | CSS class name for elements to exclude entirely from recording. Elements with this class won't appear in replays.             |
| `data-replay-block-selector`      | `string`      | `null`                           | CSS selector for elements to exclude from recording. Example: `".sensitive-content, #private-section"`.                       |
| `data-replay-ignore-class`        | `string`      | `"rr-ignore"`                    | CSS class name for elements whose input events should be ignored. The element appears but interactions aren't recorded.       |
| `data-replay-ignore-selector`     | `string`      | `null`                           | CSS selector for elements whose input events should be ignored. Example: `"input[name='credit-card']"`.                       |
| `data-replay-mask-text-class`     | `string`      | `"rr-mask"`                      | CSS class name for elements whose text content should be masked (shown as asterisks).                                         |
| `data-replay-mask-all-inputs`     | `boolean`     | `true`                           | When true, all input values are masked as asterisks for privacy. Set to `"false"` to disable.                                 |
| `data-replay-mask-input-options`  | `JSON object` | `{"password":true,"email":true}` | Specify which input types to mask. Example: `'{"password":true,"email":true,"tel":true}'`.                                    |
| `data-replay-collect-fonts`       | `boolean`     | `true`                           | When true, website fonts are collected for accurate replay rendering. Set to `"false"` to reduce data size.                   |
| `data-replay-sampling`            | `JSON object` | See below                        | Configure event sampling to reduce data volume. See sampling options below.                                                   |
| `data-replay-slim-dom-options`    | `JSON object` | See below                        | Configure which DOM elements to exclude from recording. See slimDOM options below.                                            |

### Pattern Matching Details [#pattern-matching-details]

For `data-skip-patterns` and `data-mask-patterns`, two types of wildcards are supported:

* `*` - Matches any characters within a single path segment (doesn't match across `/`)
* `**` - Matches any characters across multiple path segments (includes `/`)

Examples:

* `/admin/*` matches `/admin/dashboard` but not `/admin/users/list`
* `/admin/**` matches both `/admin/dashboard` and `/admin/users/list`
* `/blog/*/comments` matches `/blog/post-123/comments` but not `/blog/category/post/comments`

Regex patterns are also supported when prefixed with `re:`. The regex is used as-is, so add `^` and `$` if you want a full-path match.

Examples:

* `re:^/users/\\d+$` matches `/users/123` but not `/users/abc`
* `re:^/private/.*$` matches anything under `/private/`

Example usage:

```html
data-skip-patterns='["/admin/**", "/blog/drafts/*", "/preview/**"]'
data-mask-patterns='["/users/*/settings", "/accounts/**", "/orders/*/details"]'
```

Regex usage:

```html
data-skip-patterns='["re:^/private/.*$"]'
data-mask-patterns='["re:^/users/\\d+/settings$"]'
```

**Example with debugging overrides:**

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="456"
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-debounce="300"
></script>
```

## Session Replay Configuration [#session-replay-configuration]

When session replay is enabled in your site settings, you can fine-tune the recording behavior using the attributes above. This section covers the more complex configuration options.

### Privacy Controls [#privacy-controls]

Protect sensitive user information using these options:

| Option                 | Best For                                                           |
| ---------------------- | ------------------------------------------------------------------ |
| `data-replay-block-*`  | Completely hide elements (e.g., admin panels, modals with PII)     |
| `data-replay-ignore-*` | Show elements but don't record interactions (e.g., form fields)    |
| `data-replay-mask-*`   | Show element structure but hide text content (e.g., names, emails) |

**Example - Comprehensive privacy setup:**

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="123"
  data-replay-block-selector=".admin-panel, #payment-modal"
  data-replay-ignore-selector="input[name='ssn'], input[name='credit-card']"
  data-replay-mask-text-selectors='[".user-name", "#email", "[data-pii]"]'
  data-replay-mask-input-options='{"password":true,"email":true,"tel":true}'
></script>
```

### Sampling Configuration [#sampling-configuration]

The `data-replay-sampling` attribute controls how frequently events are recorded. Lower sampling rates reduce data volume but may miss some interactions.

**Default sampling configuration:**

```json
{
  "mousemove": false,
  "mouseInteraction": {
    "MouseUp": false,
    "MouseDown": false,
    "Click": true,
    "ContextMenu": false,
    "DblClick": true,
    "Focus": true,
    "Blur": true,
    "TouchStart": false,
    "TouchEnd": false
  },
  "scroll": 500,
  "input": "last",
  "media": 800
}
```

**Sampling options:**

* `mousemove`: `false` to disable, or number (ms) for sampling interval
* `scroll`: Sampling interval in milliseconds (e.g., `500` = sample every 500ms)
* `input`: `"last"` to only record final value, or `"all"` to record every keystroke
* `media`: Sampling interval for media events in milliseconds

**Example - Enable mouse tracking for UX analysis:**

```html
data-replay-sampling='{"mousemove":100,"scroll":150}'
```

### SlimDOM Options [#slimdom-options]

The `data-replay-slim-dom-options` attribute controls which DOM elements are excluded from recording to reduce data size.

**Default slimDOM configuration:**

```json
{
  "script": false,
  "comment": true,
  "headFavicon": true,
  "headWhitespace": true,
  "headMetaDescKeywords": true,
  "headMetaSocial": true,
  "headMetaRobots": true,
  "headMetaHttpEquiv": true,
  "headMetaAuthorship": true,
  "headMetaVerification": true
}
```

Set to `true` to enable all slimDOM options, or `false` to disable all:

```html
data-replay-slim-dom-options="true"
```

### Complete Example [#complete-example]

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="456"
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-debounce="300"
  data-replay-block-selector=".sensitive-content"
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-replay-mask-all-inputs="true"
  data-replay-collect-fonts="false"
  data-replay-sampling='{"mousemove":false,"scroll":500}'
></script>
```


# Segments (/de/docs/segments)





A segment is a named, reusable set of [filters](/docs/feature-guides/main-tab#filters). Instead of rebuilding "mobile visitors from Germany who came from search" every time, save it once and apply it to the main dashboard, pages, sessions, funnels, journeys, retention, and exports with one click.

Segments live inside the **Filter** button. Nothing else changes in the dashboard: applying a segment expands its filters into the same filter bar every report already reads.

## Creating a segment [#creating-a-segment]

Open the **Filter** button and switch to the **Segments** tab. There are two ways to create one:

<Steps>
  <Step>
    ### From scratch [#from-scratch]

    Click **New segment**. The dialog has its own filter editor, so you can build the definition without applying anything to the dashboard first.
  </Step>

  <Step>
    ### From the current filters [#from-the-current-filters]

    Once the dashboard has filters applied, the Segments tab offers **Save current filters as segment**. The dialog opens with those filters and a suggested name.
  </Step>
</Steps>

Every segment has:

* **Name** — what the group means to you, such as "Paid traffic" or "Logged-in users"
* **Filters** — at least one. Every filter must match; multiple values inside one filter are alternatives
* **Available on** — this site only, or every site in the organization (organization-wide segments can only be created by admins and owners)
* **Description** — optional notes for your team
* **Show on the public dashboard and private links** — off by default

<Callout type="info">
  Filters in a segment are validated against the same schema as the filter bar, so a segment can never save something the dashboard could not query.
</Callout>

## Applying a segment [#applying-a-segment]

In the **Segments*&#x2A; tab, click a segment to apply it. It appears in the filter bar as a single chip named after the segment. Click the chip to see the filters it contains; click the &#x2A;*×** to remove all of them at once.

Ad-hoc filters work alongside an applied segment. Add a filter the usual way and it is ANDed with the segment. If one of the segment's own filters is changed on the dashboard, the chip reads &#x2A;*(edited)** so you know the row no longer matches the saved definition; the segment itself is unchanged.

Segments are part of the URL, so a dashboard link with a segment applied opens the same view for whoever you share it with.

## Editing and deleting [#editing-and-deleting]

Use the &#x2A;*⋯** menu on a segment in the Segments tab, or **Edit segment** from the applied chip. Changes apply everywhere the segment is used. Deleting a segment removes it for everyone; links that already expanded its filters keep working.

## Permissions [#permissions]

| Role                                    | Read and apply                                   | Create                     | Edit and delete       |
| --------------------------------------- | ------------------------------------------------ | -------------------------- | --------------------- |
| Owner or admin                          | All segments                                     | Site and organization-wide | Any segment           |
| Member                                  | All segments                                     | Site segments              | Segments they created |
| Public dashboard or private-link viewer | Segments marked as shown on the public dashboard | —                          | —                     |

## API and MCP [#api-and-mcp]

Every analytics endpoint accepts a `segment_id` query parameter that is expanded server-side, ANDed with any `filters` you also pass. Segments themselves are managed through the [Segments endpoints](/docs/api/segments/list). The [MCP server](/docs/mcp) exposes `list_segments` and `apply_segment`.


# Self-hosted vs Cloud (/de/docs/self-host-vs-cloud)





Rybbit offers two deployment options: a fully-managed [cloud version](https://rybbit.com) and a [self-hosted](/docs/self-hosting) solution. This guide will help you choose the right option for your needs.

## Quick Comparison [#quick-comparison]

| Feature                               | Cloud                                                                                                                             | Self-Hosted                                                                                                                                          |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup Time**                        | Minutes                                                                                                                           | 30 - 120 minutes                                                                                                                                     |
| **Maintenance Required**              | None                                                                                                                              | Regular updates                                                                                                                                      |
| **Cookieless & Privacy friendly**     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Web Analytics**                     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **API**                               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Globe**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Session Replays**                   | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth="3" /> (On pro tier)</span> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Funnels**                           | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Goals**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Sessions**                          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Journeys**                          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Users**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Retention**                         | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Error tracking**                    | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Organizations/Teams**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Pages View**                        | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />                                                                                    |
| **Web Vitals**                        | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Email reports**                     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />                                                                                    |
| **Google Search Console integration** | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth="3" /> (Requires Google OAuth env vars)</span> |


# Quick start (/de/docs/self-hosting)





This guide will walk you through setting up your own instance of Rybbit using our setup script. If you want to manually setup Rybbit using the Docker Compose file, check out our [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) guide.

## Prerequisites [#prerequisites]

Before you begin, ensure you have the following:

* **A VPS:** Try to get one with at least 2GB of RAM.
* **A Domain Name:** You'll need a domain or subdomain (e.g., `tracking.yourdomain.com`) pointed to your VPS's IP address. HTTPS is required because browsers block tracking scripts served over insecure HTTP.

<Callout type="info">
  This guide has been tested on Ubuntu 24 LTS (x86\_64). If your server is ARM, it must be at least ARMv8.2-A for Clickhouse support.
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Point Your Domain to Your VPS [#point-your-domain-to-your-vps]

    Configure your domain's DNS settings to point to your VPS's public IP address. This usually involves:

    1. Finding your VPS's public IPv4 address (from your hosting provider, e.g., Hetzner).
    2. Logging into your domain registrar or DNS provider (e.g., GoDaddy, Namecheap, Cloudflare).
    3. Adding an `A` record:
       * **Host/Name:** Your desired subdomain (e.g., `tracking`) or `@` for the root domain.
       * **Value:** Your VPS's IPv4 address.
       * **Proxy Status:** When using Cloudflare, either:
         * Set to "DNS only" (recommended for most setups)
         * Or if keeping the proxy enabled, set SSL/TLS encryption mode to "Full" or "Full (strict)" in your Cloudflare dashboard under SSL/TLS settings

    <Callout type="warning">
      If you keep Cloudflare's proxy enabled and your domain has other services not running on HTTPS, using Full or Full (strict) mode might cause issues with those services. In such cases, either use "DNS only" mode or ensure all your services support HTTPS.
    </Callout>

    DNS changes might take some time to propagate globally. Use [DNS Checker](https://dnschecker.org/) to verify.
  </Step>

  <Step>
    ### Install Docker Engine [#install-docker-engine]

    Connect to your VPS via SSH.

    Follow the official Docker Engine installation instructions for your Linux distribution:
    [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
  </Step>

  <Step>
    ### Clone the Rybbit Repository [#clone-the-rybbit-repository]

    Clone the project repository from GitHub (Git is usually pre-installed on most server distributions):

    ```bash
    git clone https://github.com/rybbit-io/rybbit.git
    cd rybbit
    ```
  </Step>

  <Step>
    ### Run the Setup Script [#run-the-setup-script]

    The repository includes a setup script that configures the necessary environment variables (including generating a secure secret) and starts the application using Docker Compose.

    <Callout type="warning">
      Important: Make all scripts executable before proceeding!

      ```bash
      chmod +x *.sh
      ```
    </Callout>

    Run the setup script, replacing `your.domain.name` with the domain or subdomain you configured in the prerequisites:

    ```bash
    ./setup.sh your.domain.name
    ```

    If you want to enable 3D map visualizations, you can add the `--mapbox-token` flag:

    ```bash
    ./setup.sh your.domain.name --mapbox-token YOUR_MAPBOX_TOKEN
    ```

    The script will create a `.env` file and then build and start the containers. This might take a few minutes the first time.

    <Callout type="info">
      By default, we assume you are on a blank VPS and automatically setup a Caddy webserver. If you want to use your own webserver or need more control over the setup, check out:

      * [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) - For users with existing reverse proxies or deployment tools
      * [Advanced Self-Hosting Guide](/docs/self-hosting-guides/self-hosting-advanced) - For custom configurations and Nginx setup
    </Callout>
  </Step>

  <Step>
    ### Sign Up [#sign-up]

    Once the services are running and DNS has propagated, Caddy (the webserver) will automatically obtain an SSL certificate for your domain.

    Open your browser and navigate to `https://your.domain.name/signup` (using the domain you provided to the setup script).

    Create your admin account. You can then log in and start adding your websites!
  </Step>
</Steps>

If you run into any issues or need help, feel free to join our Discord community!


# Site settings (/de/docs/site-settings)







Access your site settings by clicking the settings icon in your site's Rybbit dashboard.

<img alt="site settings" src="__img0" />

## Privacy & Security [#privacy--security]

### Public Analytics [#public-analytics]

Make your analytics publicly accessible by enabling the "Public Analytics" toggle.

* External viewers have read-only access to your analytics data
* Viewers cannot edit settings, reports, funnels, or goals
* Your other websites are not affected

### User ID Salting [#user-id-salting]

Rybbit stores user IDs as a hashed combination of IP + user agent. This allows identifying users across sessions, but may be considered storing personally identifiable data under GDPR.

Enable "User ID Salting" to have Rybbit forget about unique users every day. If a user visits 10 times in one day, they count as one user with 10 sessions. But if they visit once a day for 10 days, they appear as a new user each day.

**Downsides of enabling user ID salting:**

* User session history beyond 24 hours is not available
* Unique user counts over periods longer than 24 hours will be inflated
* The user retention page becomes effectively useless

### Block Bot Traffic [#block-bot-traffic]

Enable "Block Bot Traffic" to prevent detected bot traffic from being tracked in your normal analytics. See [Bot detection](/docs/bot-detection) for how Rybbit identifies and stores bot traffic.

### Track IP Address [#track-ip-address]

Enable "Track IP Address" to store the IP address of visitors.

<Callout type="warn">
  This is not GDPR compliant. Only enable if you have a legitimate need and proper consent mechanisms in place.
</Callout>

## Analytics Features [#analytics-features]

### Session Replay <span className="text-green-500 text-sm">(Pro)</span> [#session-replay-pro]

Record and replay user sessions to understand user behavior. This feature allows you to see exactly how users interact with your site.

### Web Vitals <span className="text-green-500 text-sm">(Standard)</span> [#web-vitals-standard]

Track Core Web Vitals metrics including:

* **LCP** (Largest Contentful Paint)
* **CLS** (Cumulative Layout Shift)
* **INP** (Interaction to Next Paint)
* **FCP** (First Contentful Paint)
* **TTFB** (Time to First Byte)

### Error Tracking <span className="text-green-500 text-sm">(Standard)</span> [#error-tracking-standard]

Capture JavaScript errors and exceptions from your site to identify and fix issues affecting your users.

### Track Outbound Links [#track-outbound-links]

Track when users click on external links leaving your site. Enabled by default.

### Track URL Parameters [#track-url-parameters]

Include query string parameters in page tracking. Enabled by default. Disable if you want cleaner URLs in your analytics or need to exclude sensitive parameters.

### Track Initial Page View [#track-initial-page-view]

Automatically track the first page view when the tracking script loads. Enabled by default.

### Track SPA Navigation [#track-spa-navigation]

Automatically track navigation in single-page applications (SPAs). Enabled by default. This detects URL changes via the History API and tracks them as page views.

## Traffic Filtering [#traffic-filtering]

### IP Exclusions [#ip-exclusions]

Block specific IP addresses or ranges from being tracked. Supports:

* Individual IP addresses (e.g., `192.168.1.1`)
* CIDR notation (e.g., `192.168.1.0/24`)
* IPv4 ranges (e.g., `192.168.1.1-192.168.1.255`)

### Country Exclusions [#country-exclusions]

Block all traffic from specific countries using ISO country codes (e.g., `US`, `DE`, `FR`).

### Path Exclusions [#path-exclusions]

Exclude traffic to specific pages. Use `*` as a wildcard (e.g., `/admin/*` or `/preview`). Matching is case-insensitive. Up to 100 path exclusions are allowed.

### Hostname Exclusions [#hostname-exclusions]

Exclude traffic from specific hostnames such as staging or preview domains. Use `*` as a wildcard (e.g., `localhost` or `*.vercel.app`). Matching is case-insensitive. Up to 100 hostname exclusions are allowed.

### User Agent Exclusions [#user-agent-exclusions]

Exclude traffic from user agents containing any of these terms. Matching is a case-insensitive substring (e.g., `HeadlessChrome`). Up to 100 user agent exclusions are allowed.

All of these exclusions work at the server level, ensuring blocked traffic never reaches your analytics database.

## Embeds [#embeds]

Show Rybbit data on another site with an embeddable iframe.

* **Widget Embeds** show a compact live visitor widget. Enable them from the **Widget Embeds** tab. This is independent of Public Analytics and only exposes the data the widget displays. See the [Widget Embeds guide](/docs/embeds/widget) for details.
* **Dashboard Embed** shows the analytics dashboard in an iframe. Configure it from the **Dashboard Embed** tab. It uses a generated private link, not Public Analytics. See the [Dashboard Embed guide](/docs/embeds/dashboard) for details.

## Google Search Console <span className="text-green-500 text-sm">(Cloud)</span> [#google-search-console-cloud]

Connect your Google Search Console account to see search performance data alongside your analytics.

## Change Domain [#change-domain]

Update the domain for your site. Changing domains does not affect existing data - all historical analytics are preserved.

## Delete Site [#delete-site]

Permanently delete a site and all associated data.

<Callout type="warn">
  This action cannot be undone. All analytics data, reports, funnels, and goals will be permanently deleted.
</Callout>


# Tagging (/de/docs/tagging)



Tags let you label all events from a script instance with a string identifier. This is useful for A/B testing, deploy labeling, cohort segmentation, and any scenario where you want to slice your analytics by a custom dimension that applies to the entire page.

If you need Rybbit to choose a value at runtime, gradually roll out a feature, or serve remote config, use [Feature Flags](/docs/feature-flags) instead.

## How It Works [#how-it-works]

Add a `data-tag` attribute to your Rybbit script tag. Every event (pageviews, custom events, outbound clicks, etc.) sent from that page will include the tag value, which is stored in ClickHouse and available as a filter in the dashboard.

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="YOUR_SITE_ID"
  data-tag="variant-a"
></script>
```

The tag is a simple string with a maximum length of 256 characters. If `data-tag` is not set or is empty, no tag is stored.

## Use Cases [#use-cases]

### A/B Testing [#ab-testing]

Serve different script tags to different user groups and compare behavior:

```html
<!-- Variant A -->
<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-a"></script>

<!-- Variant B -->
<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-b"></script>
```

Then filter by tag in the dashboard to compare metrics between variants.

### Deploy / Release Labeling [#deploy--release-labeling]

Tag events with the current deploy version to correlate releases with changes in user behavior or errors:

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="1"
  data-tag="v2.4.1"
></script>
```

### Cohort Segmentation [#cohort-segmentation]

Label traffic from different sources, campaigns, or user segments:

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="1"
  data-tag="beta-users"
></script>
```

## Filtering by Tag [#filtering-by-tag]

Once events with tags are flowing in, you can filter by tag anywhere in the dashboard:

1. Click the **filter** button in the dashboard header
2. Select **Tag** from the filter parameter dropdown
3. Choose an operator (is, is not, contains, etc.)
4. Enter the tag value

The tag filter works on all dashboard pages including overview, pages, referrers, events, users, funnels, and goals.

## API Usage [#api-usage]

When sending events via the [HTTP API](/docs/api/sending-events), include `tag` in the request body:

```json
{
  "site_id": "YOUR_SITE_ID",
  "type": "pageview",
  "hostname": "example.com",
  "pathname": "/",
  "tag": "variant-a"
}
```

## Important Notes [#important-notes]

* Each script instance can only have one tag. If you need multiple dimensions, consider using [custom event properties](/docs/track-events) instead.
* Tags are set at the script level, not per-event. All events from a page load share the same tag.
* The tag value is stored as-is (no hashing or transformation).
* Empty or missing `data-tag` attributes result in no tag being stored.

**Related Documentation:**

* [Tracking Script](/docs/script)
* [Track Events](/docs/track-events)
* [Identify Users](/docs/identify-users)


# Teams (/de/docs/teams)







Teams let you group sites together and control which organization members can access them. This is useful for organizations managing multiple properties where different people are responsible for different sites.

Access teams by clicking on "Teams" or going to [app.rybbit.io/settings/teams](https://app.rybbit.io/settings/teams).

<img alt="teams" src="__img0" />

## How Teams Work [#how-teams-work]

A team has three things:

* **A name** — identifies the team (e.g. "Marketing Sites", "Client Projects")
* **Members** — organization members assigned to the team
* **Sites** — the sites that belong to the team

When a member is assigned to a team, they can access all sites within that team. Admins and owners always have access to all sites regardless of team assignments.

<Callout type="info">
  Teams are an organizational tool for admins and owners. Members with the "Member" role can only see sites that belong to their assigned teams (unless they have unrestricted access).
</Callout>

## Creating a Team [#creating-a-team]

1. Go to **Settings > Teams**
2. Click the **Create Team** button
3. Enter a team name
4. Select which members should belong to the team
5. Select which sites the team should have access to
6. Click **Create Team**

You can also create a team directly from the team filter on the home page.

## Managing Teams [#managing-teams]

### Editing a Team [#editing-a-team]

Click the edit icon on any team card to update its name, members, or site assignments.

### Deleting a Team [#deleting-a-team]

Click the delete icon on a team card. Sites assigned to the team will become unassigned and visible to all members.

<Callout type="warn">
  Deleting a team removes all member-to-site associations through that team. Members who only had access via the deleted team will lose access to those sites.
</Callout>

## Filtering by Team [#filtering-by-team]

On the home page, use the team selector in the toolbar to filter the site list by team. The options are:

* **All Teams** — show all sites
* **No Team** — show only sites not assigned to any team
* **Specific team** — show only sites belonging to that team

## Assigning Teams During Invitation [#assigning-teams-during-invitation]

When [inviting a new member](/docs/inviting-users), you can optionally assign them to a team. When the member accepts the invitation, they will automatically be added to the selected team.

## Permissions [#permissions]

| Role       | Can create teams | Can edit/delete teams | Can view team-restricted sites     |
| ---------- | ---------------- | --------------------- | ---------------------------------- |
| **Owner**  | Yes              | Yes                   | All sites                          |
| **Admin**  | Yes              | Yes                   | All sites                          |
| **Member** | No               | No                    | Only sites in their assigned teams |


# Track Events (/de/docs/track-events)



The script exposes a global object `window.rybbit` with functions for manual tracking of events, as well as the ability to track events using data attributes on HTML elements.

## Using Data Attributes [#using-data-attributes]

You can track custom events by adding data attributes to any HTML element:

```html
<!-- Basic event tracking -->
<button data-rybbit-event="signup_clicked">Sign Up</button>

<!-- Event with custom properties -->
<button
  data-rybbit-event="purchase_click"
  data-rybbit-prop-product="premium"
  data-rybbit-prop-price="49.99"
>
  Buy Now
</button>
```

This approach requires no JavaScript and works on any clickable element.

## Available Functions [#available-functions]

### `window.rybbit.event(eventName, properties)` [#windowrybbiteventeventname-properties]

Tracks a custom event with optional properties.

* `eventName` (String): The name of the custom event (max 256 characters).
* `properties` (Object, Optional): An object containing custom data (max 2KB characters). Only strings numbers are supported as values.

```javascript
// Track a simple custom event
window.rybbit.event("Signup Button Clicked");

// Track a custom event with properties
window.rybbit.event("Item Added To Cart", {
  itemId: "PROD123",
  price: 49.99,
  category: "Clothing"
});
```

### `window.rybbit.pageview()` [#windowrybbitpageview]

Tracks a pageview. Useful when automatic SPA navigation tracking is disabled in your site settings, or when you need to manually trigger a pageview.

```javascript
// Track a pageview
window.rybbit.pageview();
```

## TypeScript Support [#typescript-support]

Put this as `rybbit.d.ts` anywhere in your project to avoid having to do `(window as any).rybbit.event()` everywhere.

```typescript
interface Rybbit {
    /**
     * Tracks a page view
     */
    pageview: () => void;

    /**
     * Tracks a custom event
     * @param name Name of the event
     * @param properties Optional properties for the event
     */
    event: (name: string, properties?: Record<string, any>) => void;

    /**
     * Sets a custom user ID for tracking logged-in users
     * @param userId The user ID to set (will be stored in localStorage)
     * @param traits Optional user metadata (email, name, custom fields)
     */
    identify: (userId: string, traits?: Record<string, unknown>) => void;

    /**
     * Updates traits for the currently identified user
     * @param traits User metadata to merge with existing traits
     */
    setTraits: (traits: Record<string, unknown>) => void;

    /**
     * Clears the stored user ID
     */
    clearUserId: () => void;

    /**
     * Gets the currently set user ID
     * @returns The current user ID or null if not set
     */
    getUserId: () => string | null;

    /**
     * Manually tracks outbound link clicks
     * @param url The URL of the outbound link
     * @param text Optional text content of the link
     * @param target Optional target attribute of the link
     */
    trackOutbound: (url: string, text?: string, target?: string) => void;

    /**
     * Evaluates a feature flag and returns its value. Reading a flag records a
     * feature flag exposure once per flag value/version.
     * @param key The flag key
     * @param fallback Value returned before flags resolve or if the flag is inactive
     */
    flag: <T = unknown>(key: string, fallback?: T) => T;

    /**
     * Returns the payload for a feature flag or its selected variant.
     * Use this for remote config and multivariate payloads.
     * @param key The flag key
     * @param fallback Value returned before flags resolve or if the flag is inactive
     */
    flagPayload: <T = unknown>(key: string, fallback?: T) => T;

    /**
     * Returns all evaluated flag values keyed by flag key
     */
    flags: () => Record<string, unknown>;

    /**
     * Returns all available flag payloads keyed by flag key
     */
    flagPayloads: () => Record<string, unknown>;

    /**
     * Runs a callback once the tracking script and feature flags are ready.
     * Use this before reading flags during page initialization.
     * @param callback Receives the ready rybbit instance
     */
    onReady: (callback: (rybbit: Rybbit) => void) => void;
}

declare global {
    interface Window {
        rybbit: Rybbit;
    }
}

export {};
```

## Server-Side Tracking [#server-side-tracking]

For tracking events from server-side applications, mobile apps, or any platform outside the browser, you can use the HTTP API. This is useful for:

* Server-side event tracking (Node.js, Python, Go, etc.)
* Mobile app analytics (iOS, Android, Flutter)
* Backend integrations and webhooks
* Scenarios where the JavaScript snippet can't be used

See the [API documentation](/docs/api/sending-events) for detailed examples in multiple languages including authentication, parameters, and rate limiting information.

***

**Related Documentation:**

* [Identify Users](/docs/identify-users)
* [Behavior Analytics - Events Tab](/docs/behavior-analytics/events)
* [Behavior Analytics - Users Tab](/docs/behavior-analytics/users)
* [Behavior Analytics - Sessions Tab](/docs/behavior-analytics/sessions)
* [Product Analytics - Retention Guide](/docs/product-analytics/retention_guide)
* [Product Analytics - Funnels](/docs/product-analytics/funnels_guide)
* [API - Sending Events](/docs/api/sending-events)
* [Blog: Churn Rate vs Retention Rate](/blog/churn-rate-vs-retention-rate)
* [Web SDK Reference](/docs/sdks/web)


# Troubleshooting (/de/docs/troubleshooting)





## Full Docker Cleanup [#full-docker-cleanup]

If you encounter issues with Docker containers, images, or volumes and need to start fresh, you can perform a complete Docker cleanup. This will remove all containers, images, volumes, and custom networks.

<Callout type="warn">
  **Warning**: This will remove ALL Docker containers, images, and volumes on your system, not just Rybbit-related ones. Make sure you don't have other important Docker containers running.
</Callout>

### Steps for Complete Docker Cleanup [#steps-for-complete-docker-cleanup]

<Steps>
  <Step>
    ### Remove your environment file [#remove-your-environment-file]

    ```bash
    rm .env
    ```
  </Step>

  <Step>
    ### Stop all running containers: [#stop-all-running-containers]

    ```bash
    docker stop $(docker ps -q)
    ```
  </Step>

  <Step>
    ### Remove all containers (both running and stopped): [#remove-all-containers-both-running-and-stopped]

    ```bash
    docker rm -f $(docker ps -aq)
    ```
  </Step>

  <Step>
    ### Remove all images: [#remove-all-images]

    ```bash
    docker rmi -f $(docker images -q)
    ```
  </Step>

  <Step>
    ### Remove all volumes: [#remove-all-volumes]

    ```bash
    docker volume rm -f $(docker volume ls -q)
    ```
  </Step>

  <Step>
    ### Remove all custom networks (preserves default networks): [#remove-all-custom-networks-preserves-default-networks]

    ```bash
    docker network rm $(docker network ls | grep -v "bridge\|host\|none" | awk '{print $1}')
    ```
  </Step>
</Steps>

### Alternative: Rybbit-Specific Cleanup [#alternative-rybbit-specific-cleanup]

If you only want to clean up Rybbit-related Docker resources without affecting other containers, use these commands instead:

```bash
# Stop and remove Rybbit containers
docker-compose down

# Remove Rybbit images
docker-compose down --rmi all

# Remove Rybbit volumes (this will delete your data!)
docker-compose down --volumes

# Complete Rybbit cleanup
docker-compose down --rmi all --volumes --remove-orphans
```

### After Cleanup [#after-cleanup]

Once you've completed the cleanup, you can restart Rybbit by following the setup instructions:

```bash
# Copy environment file
cp .env.example .env

# Edit .env with your configuration
# Then start the services
docker-compose up -d
```

## ClickHouse keeps crashing on a Proxmox VM [#clickhouse-keeps-crashing-on-a-proxmox-vm]

ClickHouse requires the SSE 4.2 instruction set. Proxmox VMs default to a generic CPU type (like `kvm64` or `x86-64-v2-AES`) that doesn't expose all of the host CPU's instruction sets to the VM, which causes ClickHouse to fail with `Illegal instruction` errors or get stuck in a restart loop.

To fix this, set the VM's CPU type to `host` so it passes through the physical CPU directly:

<Steps>
  <Step>
    ### Open the VM's hardware settings [#open-the-vms-hardware-settings]

    In the Proxmox web UI, select your VM, then go to **Hardware** → **Processors** → **Edit**.
  </Step>

  <Step>
    ### Set the CPU type to `host` [#set-the-cpu-type-to-host]

    Change the **Type** dropdown to `host` and click **OK**.
  </Step>

  <Step>
    ### Fully stop and start the VM [#fully-stop-and-start-the-vm]

    A reboot from inside the guest is not enough — do a full **Stop** and then **Start** from Proxmox for the CPU change to take effect.
  </Step>
</Steps>

<Callout type="info">
  The `host` CPU type can prevent live migration between Proxmox nodes with different CPU models. If you need migration, any CPU type that includes SSE 4.2 (e.g. `x86-64-v2-AES` on a host that supports it, or newer) may also work — but `host` is the most reliable option.
</Callout>

## I ran out of disk space [#i-ran-out-of-disk-space]

Regular web analytics events take up almost no space in Clickhouse, so it is very unlikely that you ran out of disk space from from this. There are two main reasons why you might have run out of disk space:

### 1. You are using session replay [#1-you-are-using-session-replay]

On self-hosted instances where we don't have access to S3 compatible object storage, session replays are stored in Clickhouse. Each session replay is at least 1000x the data footprint of the web analytics events. So it's very easy to run out of disk space.

We have a 30 day retention policy for session replays events, so if you turn off session replay, your disk space will slowly come back. If you need to immediately free up space, you can truncate the session replays table:

```bash
docker exec -it clickhouse clickhouse-client --database analytics

TRUNCATE TABLE session_replay_events;
TRUNCATE TABLE session_replay_metadata;
```

### 2. You didn't mount the Clickhouse log suppression configs [#2-you-didnt-mount-the-clickhouse-log-suppression-configs]

In our [docker-compose.yml](https://github.com/rybbit-io/rybbit/blob/master/docker-compose.yml), we have a config for Clickhouse that suppresses logs. Clickhouse stores a ton of logs in the log tables by default. This will quickly fill up your disk space if left unchecked.

If you follow the standard installation process, the configs are already mounted for you. If you rolled your own Docker setup, you need to mount the configs manually.


# Migration to v1.0 (/de/docs/v1-migration)





This guide covers the breaking changes and migration steps when upgrading to Rybbit v1.0.

## API Path Changes [#api-path-changes]

In v1.0, we've simplified the reverse proxy configuration by having the backend expect requests with the `/api/` prefix. This eliminates the need for custom path rewriting in reverse proxy configurations.

### If You're Using the Built-in Caddy Server [#if-youre-using-the-built-in-caddy-server]

**No action required.** The built-in Caddy server configuration has been automatically updated and will work without any changes on your part.

### If You're Using a Custom Reverse Proxy [#if-youre-using-a-custom-reverse-proxy]

**You need to remove any custom API path rewriting** from your reverse proxy configuration.

<Callout type="warn">
  **Important:** If you were using a custom reverse proxy (Nginx, Apache, etc.) with path rewriting rules for the `/api/` endpoint, you must remove these rules when upgrading to v1.0.
</Callout>

#### What to Remove [#what-to-remove]

Remove any configuration that strips or rewrites the `/api/` prefix when forwarding requests to the backend. Common examples include:

**Nginx - Remove these patterns:**

```nginx
# ❌ Remove this type of configuration
location /api/ {
    rewrite ^/api(/.*)$ $1 break;  # Remove this line
    proxy_pass http://localhost:3001/;  # Change trailing slash
}
```

**Update to:**

```nginx
# ✅ Correct v1.0 configuration
location /api/ {
    proxy_pass http://localhost:3001;  # No trailing slash, no rewrite
    proxy_set_header Host $host;
    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;
}
```

**Apache - Remove these patterns:**

```apache
# ❌ Remove this type of configuration
ProxyPass /api/ http://localhost:3001/
ProxyPassReverse /api/ http://localhost:3001/
```

**Update to:**

```apache
# ✅ Correct v1.0 configuration
ProxyPass /api/ http://localhost:3001/api/
ProxyPassReverse /api/ http://localhost:3001/api/
```

**Docker Compose with custom location rules:**

```yaml
# ❌ Remove rewrite rules like this
location /api/ {
    rewrite ^/api(/.*)$ $1 break;
    proxy_pass http://rybbit_backend:3001;
}
```

**Update to:**

```yaml
# ✅ Correct v1.0 configuration
location /api/ {
    proxy_pass http://rybbit_backend:3001;
}
```

#### Why This Change? [#why-this-change]

This change simplifies the reverse proxy setup and eliminates a common source of configuration errors. The backend now handles the `/api/` prefix internally, making the setup more straightforward and consistent across different proxy solutions.

## Migration Steps [#migration-steps]

1. **Backup your current configuration** before making any changes
2. **Update your reverse proxy configuration** to remove API path rewriting (if applicable)
3. **Update to v1.0** using the update script:
   ```bash
   ./update.sh
   ```
4. **Verify your setup** by checking that your Rybbit instance is accessible and functioning correctly

## Need Help? [#need-help]

If you encounter issues during migration or need assistance with your specific reverse proxy setup, feel free to join our Discord community for support.


# Compare Channel Performance (/de/docs/api/channel-performance)





The channel that sends the most visitors is rarely the channel that sends the most *customers*. This guide ranks each acquisition channel by conversion rate so you can see which sources punch above their weight — and which ones are vanity traffic.

**Endpoints used:**

* [`GET /metric`](/docs/api/overview/metric) — sessions broken down by channel
* [`GET /goals`](/docs/api/goals/list) — conversion metrics, scoped with a channel filter

<Callout type="info">
  The key technique here is the [`filters` parameter](/docs/api/getting-started#filter-parameters). Almost every endpoint accepts it, so you can take any site-wide metric and recompute it for a single segment — here, one channel at a time.
</Callout>

## The workflow [#the-workflow]

<Steps>
  <Step>
    **List your channels** and their session counts with `metric?parameter=channel`.
  </Step>

  <Step>
    **For each channel, fetch your goal's conversion rate** by calling `/goals` with a `channel` filter applied.
  </Step>

  <Step>
    **Rank by conversion rate** to reveal which channels actually drive outcomes.
  </Step>
</Steps>

## Full script [#full-script]

This script ranks every channel by the conversion rate of a chosen goal (here, goal `1` — your signup goal). Swap in whichever goal matters to your business.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="channel-performance.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const PRIMARY_GOAL_ID = 1; // the goal you care about

    const range = { start_date: '2024-01-01', end_date: '2024-01-31', time_zone: 'America/New_York' };

    async function get(path, params) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    // 1. All channels with their session counts
    async function getChannels() {
      const { data } = await get('/metric', { parameter: 'channel', limit: 20, ...range });
      return data.data; // [{ value: 'Organic Search', count: 5400, ... }]
    }

    // 2. Conversion rate for one channel, scoped with a filter
    async function goalForChannel(channel) {
      const filters = JSON.stringify([{ parameter: 'channel', type: 'equals', value: [channel] }]);
      const { data } = await get('/goals', { filters, ...range });
      return data.find((g) => g.goalId === PRIMARY_GOAL_ID);
    }

    async function rankChannels() {
      const channels = await getChannels();

      const rows = await Promise.all(
        channels.map(async (c) => {
          const goal = await goalForChannel(c.value);
          return {
            channel: c.value || 'Direct',
            sessions: c.count,
            conversions: goal?.total_conversions ?? 0,
            // conversion_rate comes back as a 0–1 fraction
            conversionRate: (goal?.conversion_rate ?? 0) * 100,
          };
        })
      );

      return rows.sort((a, b) => b.conversionRate - a.conversionRate);
    }

    rankChannels().then((rows) => {
      console.log('Channel'.padEnd(18), 'Sessions'.padStart(10), 'Conv.'.padStart(8), 'Rate'.padStart(8));
      for (const r of rows) {
        console.log(
          r.channel.padEnd(18),
          r.sessions.toLocaleString().padStart(10),
          String(r.conversions).padStart(8),
          `${r.conversionRate.toFixed(2)}%`.padStart(8)
        );
      }
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python title="channel_performance.py"
    import os, json, requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    PRIMARY_GOAL_ID = 1  # the goal you care about

    RANGE = {"start_date": "2024-01-01", "end_date": "2024-01-31", "time_zone": "America/New_York"}

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def get(path, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def get_channels():
        # 1. All channels with their session counts
        return get("/metric", parameter="channel", limit=20, **RANGE)["data"]["data"]


    def goal_for_channel(channel):
        # 2. Conversion rate for one channel, scoped with a filter
        filters = json.dumps([{"parameter": "channel", "type": "equals", "value": [channel]}])
        goals = get("/goals", filters=filters, **RANGE)["data"]
        return next((g for g in goals if g["goalId"] == PRIMARY_GOAL_ID), None)


    def rank_channels():
        rows = []
        for c in get_channels():
            goal = goal_for_channel(c["value"])
            rows.append({
                "channel": c["value"] or "Direct",
                "sessions": c["count"],
                "conversions": goal["total_conversions"] if goal else 0,
                # conversion_rate comes back as a 0–1 fraction
                "conversion_rate": (goal["conversion_rate"] if goal else 0) * 100,
            })
        return sorted(rows, key=lambda r: r["conversion_rate"], reverse=True)


    print(f"{'Channel':<18}{'Sessions':>10}{'Conv.':>8}{'Rate':>8}")
    for r in rank_channels():
        print(f"{r['channel']:<18}{r['sessions']:>10,}{r['conversions']:>8}{r['conversion_rate']:>7.2f}%")
    ```
  </Tab>
</Tabs>

## Reading the result [#reading-the-result]

```text
Channel             Sessions   Conv.    Rate
Referral               1,820     310    17.03%
Organic Search         5,400     642    11.89%
Direct                 4,220     451    10.69%
Email                    980      88     8.98%
Paid Search            2,310     142     6.15%
Social                 6,150     119     1.93%
```

Social sends the **most** traffic (6,150 sessions) but converts the **worst** (1.93%). Referral sends a fraction of the volume but converts nine times better. The takeaway writes itself: the referral partnerships deserve more investment, and the social strategy needs a hard look before more budget goes into it.

<Callout type="warn">
  Conversion rate alone can mislead on tiny samples — Email looks healthy at 9% but it's only 88 conversions. Always show the raw `sessions` and `conversions` columns next to the rate so a channel with 12 sessions and one fluke conversion doesn't top your list.
</Callout>

## Variations [#variations]

* **By UTM campaign instead of channel:** swap `parameter: 'channel'` for `parameter: 'utm_campaign'`, and filter on `utm_campaign` in the goals call. Same code, campaign-level granularity.
* **Engagement instead of conversion:** call [`/overview`](/docs/api/overview/overview) with the channel filter to compare `bounce_rate` and `session_duration` per channel — useful when you don't have a goal defined yet.
* **Full-funnel by channel:** run [`/funnels/analyze`](/docs/api/funnels/analyze) with a channel filter to see *where* in the funnel each channel's visitors fall out, not just the final rate.

## Next steps [#next-steps]

* [Find Where Users Drop Off](/docs/api/funnel-dropoff) — once you know your best channels, fix the funnel they pour into.
* [Automated Weekly Report](/docs/api/weekly-report) — add a channel league table to a scheduled digest.


# Find Where Users Drop Off (/de/docs/api/funnel-dropoff)





A funnel tells you *how many* people fall out at each step. The journeys endpoint tells you *where they went instead*. Putting them together turns "our signup funnel leaks at the pricing page" into "people leave the pricing page for the FAQ — they have unanswered questions."

**Endpoints used:**

* [`POST /funnels/analyze`](/docs/api/funnels/analyze) — step-by-step conversion and drop-off rates
* [`GET /journeys`](/docs/api/insights/journeys) — the most common navigation paths

## The workflow [#the-workflow]

<Steps>
  <Step>
    **Analyze the funnel** to get a drop-off rate for every step.
  </Step>

  <Step>
    **Find the worst step** — the one with the highest `dropoff_rate`.
  </Step>

  <Step>
    **Pull journeys that start at that step's page** using `stepFilters`, so you can see the most common next page for people who were there.
  </Step>
</Steps>

## Step 1 — Analyze the funnel [#step-1--analyze-the-funnel]

Define the path a converting user should take and post it to the analyze endpoint.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="Analyze the funnel"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;

    const range = { start_date: '2024-01-01', end_date: '2024-01-31', time_zone: 'America/New_York' };

    const funnelSteps = [
      { type: 'page',  value: '/',                 name: 'Homepage' },
      { type: 'page',  value: '/pricing',          name: 'Pricing' },
      { type: 'page',  value: '/signup',           name: 'Signup' },
      { type: 'event', value: 'signup_complete',   name: 'Complete' },
    ];

    async function analyzeFunnel() {
      const url = new URL(`${API}/api/sites/${SITE}/funnels/analyze`);
      Object.entries(range).forEach(([k, v]) => url.searchParams.set(k, v));

      const res = await fetch(url, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ steps: funnelSteps }),
      });
      const { data } = await res.json();
      return data; // array of { step_number, step_name, sessions, conversion_rate, dropoff_rate }
    }
    ```
  </Tab>

  <Tab value="Python">
    ```python title="Analyze the funnel"
    import os, requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]

    RANGE = {"start_date": "2024-01-01", "end_date": "2024-01-31", "time_zone": "America/New_York"}

    FUNNEL_STEPS = [
        {"type": "page",  "value": "/",               "name": "Homepage"},
        {"type": "page",  "value": "/pricing",        "name": "Pricing"},
        {"type": "page",  "value": "/signup",         "name": "Signup"},
        {"type": "event", "value": "signup_complete", "name": "Complete"},
    ]


    def analyze_funnel():
        res = requests.post(
            f"{API}/api/sites/{SITE}/funnels/analyze",
            params=RANGE,
            json={"steps": FUNNEL_STEPS},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        res.raise_for_status()
        return res.json()["data"]  # list of step results
    ```
  </Tab>
</Tabs>

A response looks like this — note that `dropoff_rate` is the percentage who left **between the previous step and this one**:

```json
{
  "data": [
    { "step_number": 1, "step_name": "Homepage", "sessions": 10000, "conversion_rate": 100,  "dropoff_rate": 0 },
    { "step_number": 2, "step_name": "Pricing",  "sessions": 4500,  "conversion_rate": 45,   "dropoff_rate": 55 },
    { "step_number": 3, "step_name": "Signup",   "sessions": 1800,  "conversion_rate": 18,   "dropoff_rate": 60 },
    { "step_number": 4, "step_name": "Complete", "sessions": 1080,  "conversion_rate": 10.8, "dropoff_rate": 40 }
  ]
}
```

## Step 2 — Find the worst step [#step-2--find-the-worst-step]

The leak isn't always the step with the fewest sessions — it's the step with the steepest **drop-off**. Pick the maximum `dropoff_rate`.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="Find the biggest leak"
    function biggestLeak(steps) {
      // Skip step 1 — it always has 0% drop-off
      return steps
        .filter((s) => s.step_number > 1)
        .reduce((worst, s) => (s.dropoff_rate > worst.dropoff_rate ? s : worst));
    }

    const steps = await analyzeFunnel();
    const leak = biggestLeak(steps);
    const enteredStep = steps[leak.step_number - 2]; // the step they were on before leaving

    console.log(
      `Worst leak: ${leak.dropoff_rate}% of users left after "${enteredStep.step_name}" ` +
      `instead of reaching "${leak.step_name}".`
    );
    ```
  </Tab>

  <Tab value="Python">
    ```python title="Find the biggest leak"
    def biggest_leak(steps):
        # Skip step 1 — it always has 0% drop-off
        return max((s for s in steps if s["step_number"] > 1), key=lambda s: s["dropoff_rate"])


    steps = analyze_funnel()
    leak = biggest_leak(steps)
    entered_step = steps[leak["step_number"] - 2]  # the step they were on before leaving

    print(
        f'Worst leak: {leak["dropoff_rate"]}% of users left after "{entered_step["step_name"]}" '
        f'instead of reaching "{leak["step_name"]}".'
    )
    ```
  </Tab>
</Tabs>

In the example above, the steepest drop-off is **60%, between Pricing and Signup** — of the 4,500 people who reached the pricing page, only 1,800 went on to signup. That makes the **pricing page** the one to investigate: it's where the audience was sitting right before the biggest leak.

## Step 3 — See where the leavers went [#step-3--see-where-the-leavers-went]

The [journeys endpoint](/docs/api/insights/journeys) ranks the most common page paths. Use `stepFilters` to anchor step `0` to the page people were dropping from — now every returned journey shows you a common *next* page for that audience.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="What did they do after the leaky page?"
    async function journeysFrom(page) {
      const stepFilters = JSON.stringify({ '0': page });
      const url = new URL(`${API}/api/sites/${SITE}/journeys`);
      url.searchParams.set('steps', '2');
      url.searchParams.set('limit', '10');
      url.searchParams.set('stepFilters', stepFilters);
      Object.entries(range).forEach(([k, v]) => url.searchParams.set(k, v));

      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      const { journeys } = await res.json();
      return journeys;
    }

    // The leaky step's page — '/pricing' in our example
    const leakyPage = funnelSteps[leak.step_number - 2].value;
    const journeys = await journeysFrom(leakyPage);

    console.log(`Where users go after ${leakyPage}:`);
    journeys
      .filter((j) => j.path[1] && j.path[1] !== '/signup') // exclude the intended next step
      .slice(0, 5)
      .forEach((j) => console.log(`  → ${j.path[1]}  (${j.count} sessions, ${j.percentage}%)`));
    ```
  </Tab>

  <Tab value="Python">
    ```python title="What did they do after the leaky page?"
    import json


    def journeys_from(page):
        res = requests.get(
            f"{API}/api/sites/{SITE}/journeys",
            params={"steps": 2, "limit": 10, "stepFilters": json.dumps({"0": page}), **RANGE},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        res.raise_for_status()
        return res.json()["journeys"]


    # The leaky step's page — '/pricing' in our example
    leaky_page = FUNNEL_STEPS[leak["step_number"] - 2]["value"]
    journeys = journeys_from(leaky_page)

    print(f"Where users go after {leaky_page}:")
    for j in [j for j in journeys if len(j["path"]) > 1 and j["path"][1] != "/signup"][:5]:
        print(f'  → {j["path"][1]}  ({j["count"]} sessions, {j["percentage"]}%)')
    ```
  </Tab>
</Tabs>

### The insight [#the-insight]

```text
Where users go after /pricing:
  → /faq          (1,240 sessions, 27.6%)
  → /             (820 sessions, 18.2%)
  → /enterprise   (610 sessions, 13.6%)
```

More than a quarter of people who hit Pricing and didn't sign up went to the FAQ — a strong signal that pricing raises questions your FAQ has to answer. That's a far more actionable finding than "the pricing page has a 60% drop-off."

<Callout type="info">
  **Quantify before you act.*&#x2A; Combine the funnel and journey numbers into a one-line business case: &#x2A;"2,700 users/month leave Pricing; 28% head to the FAQ. Surfacing the top FAQ answers on the pricing page could recover a meaningful share of them."*
</Callout>

## Next steps [#next-steps]

* [Compare Marketing Channel Performance](/docs/api/channel-performance) — find out which traffic sources fill the top of this funnel with people who actually convert.
* [Funnels API reference](/docs/api/funnels/analyze) — event steps, property matching, and per-step session lookups.


# Getting Started (/de/docs/api/getting-started)





<Callout type="warn">
  The API is currently in beta. There may be breaking changes as we continue to improve and expand the API.
</Callout>

## API Playground [#api-playground]

The easiest way to explore and test the API is using the built-in **API Playground** in your Rybbit dashboard. Access it by navigating to any site and clicking "API Playground" in the sidebar.

The playground provides:

* **Endpoint browser** - Browse all available API endpoints
* **Parameter controls** - Configure request parameters with a visual interface
* **Exact time ranges** - Test date ranges with optional start and end times
* **Live responses** - See real API responses with your actual data
* **Code generation** - Copy ready-to-use code snippets

This is the recommended way to familiarize yourself with the API before integrating it into your applications.

## Guides [#guides]

Looking for what to *build* with the API? These end-to-end recipes chain endpoints together to solve a real problem:

* [**Automated Weekly Report**](/docs/api/weekly-report) — a scheduled digest of last week's traffic, week-over-week change, and top pages and sources.
* [**Find Where Users Drop Off**](/docs/api/funnel-dropoff) — locate the biggest leak in a funnel, then see where the people who abandon go instead.
* [**Compare Channel Performance**](/docs/api/channel-performance) — rank acquisition channels by how well they convert, not just how much traffic they send.
* [**Build a Live Visitor Feed**](/docs/api/live-feed) — poll the events endpoint for a real-time activity stream you can render or alert on.
* [**Export Events to a Warehouse**](/docs/api/export-events) — backfill your full event history and keep it in sync with an incremental job.

## Authentication [#authentication]

All API requests must include authentication using one of the following methods:

### Bearer Token (Recommended) [#bearer-token-recommended]

```bash
Authorization: Bearer your_api_key_here
```

### Query Parameter (Testing Only) [#query-parameter-testing-only]

```bash
?api_key=your_api_key_here
```

<Callout type="warn">
  Query parameters expose API keys in server logs and browser history. Use only for quick testing.
</Callout>

## Generating API Keys [#generating-api-keys]

Rybbit has two kinds of API keys:

* **Organization API keys** (recommended for integrations) — the organization's own credential. They can access every site in the organization and keep working when team members leave. Only organization admins and owners can create and manage them.
* **Personal API keys** — act as you, with exactly your access, including any site restrictions, across every organization you belong to. Best for personal scripts and for connecting MCP clients.

### Organization keys [#organization-keys]

1. Navigate to **Settings → Organization** in your Rybbit dashboard
2. Scroll to the **Organization API Keys** section (visible to admins and owners)
3. Enter a name for the key and click **Create**
4. Copy the key immediately (it won't be shown again)

### Personal keys [#personal-keys]

1. Navigate to **Settings → Account** in your Rybbit dashboard
2. Scroll to the **Personal API Keys** section
3. Enter a name for the key and click **Create**
4. Copy the key immediately (it won't be shown again)

Both kinds support restricting a key to specific permissions when you create it — leave restrictions off for a full-access key.

### Rate Limits (Cloud Only) [#rate-limits-cloud-only]

Requests are limited in two ways: a **burst** limit that is the same on every plan, and a **daily quota** that depends on your plan.

| Plan             | Burst                      | Daily quota             |
| ---------------- | -------------------------- | ----------------------- |
| **Free / Basic** | API keys not available     | —                       |
| **Standard**     | 50 requests per 10 seconds | 5,000 requests per day  |
| **Pro**          | 50 requests per 10 seconds | 25,000 requests per day |

The burst limit is a bucket of 50 requests that refills continuously at 5 requests per second. You can spend all 50 at once, then keep going at 5 per second — so short spikes are fine and there is no window boundary to line up with.

The daily quota resets at **00:00 UTC**.

Requests refused by the burst limit don't count against your daily quota.

#### Which budget a request is charged to [#which-budget-a-request-is-charged-to]

Limits apply per **credential owner**, never per key — creating more keys splits an existing budget rather than adding to it:

| Credential                       | Budget                                                                                      |
| -------------------------------- | ------------------------------------------------------------------------------------------- |
| **Organization key** (`rb_org_`) | The organization's. All of an organization's keys share it.                                 |
| **Personal key**                 | Yours. All of your personal keys share one budget, across every organization you belong to. |
| **OAuth token** (MCP)            | Yours, the same budget as your personal keys.                                               |

A personal key's quota follows the most generous plan among the organizations you belong to.

Self-hosted instances are not rate limited at all — neither tier applies, and no rate limit headers are sent.

#### Reading your remaining budget [#reading-your-remaining-budget]

Analytics and management endpoints report your current budget on every response, so you can pace a client without waiting to be rejected:

| Header                                      | Meaning                                        |
| ------------------------------------------- | ---------------------------------------------- |
| `X-RateLimit-Burst-Limit` / `-Remaining`    | Burst bucket size and tokens left              |
| `X-RateLimit-Burst-Reset`                   | Seconds until the bucket is full again         |
| `X-RateLimit-Daily-Limit` / `-Remaining`    | Daily quota and requests left today            |
| `X-RateLimit-Daily-Reset`                   | Seconds until 00:00 UTC                        |
| `RateLimit-Limit` / `-Remaining` / `-Reset` | Whichever of the two is closest to running out |

Treat these as advisory: a few endpoints resolve credentials outside the standard path and omit them. `Retry-After` on a `429` is always present.

#### When you hit a limit [#when-you-hit-a-limit]

A `429` names the limit you hit and tells you how long to wait, in seconds:

```json
{
  "error": "Rate limit exceeded",
  "scope": "daily",
  "limit": 5000,
  "retryAfter": 34200
}
```

`scope` is `burst` or `daily`, and the same value is in the `Retry-After` header. The difference matters: a `burst` rejection clears in about a second, while a `daily` one lasts until the quota resets. Back off accordingly rather than retrying straight away.

***

## Common Parameters [#common-parameters]

The following parameters are shared across all analytics endpoints.

### Time Parameters [#time-parameters]

All endpoints require date-based, exact datetime, or relative time parameters:

<TypeTable
  type="{
  start_date: {
    description: 'Start date for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD (e.g., &#x22;2024-01-15&#x22;)',
    required: false,
  },
  end_date: {
    description: 'End date for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD (e.g., &#x22;2024-01-31&#x22;)',
    required: false,
  },
  time_zone: {
    description: 'IANA timezone identifier',
    type: 'string',
    typeDescription: 'e.g., &#x22;America/New_York&#x22;, &#x22;Europe/London&#x22;, &#x22;Asia/Tokyo&#x22;. Required with date and exact datetime ranges.',
    required: false,
  },
  start_datetime: {
    description: 'Exact UTC start timestamp for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD HH:mm:ss (e.g., &#x22;2024-01-15 13:00:00&#x22;)',
    required: false,
  },
  end_datetime: {
    description: 'Exact UTC end timestamp for the query period. This boundary is exclusive.',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD HH:mm:ss (e.g., &#x22;2024-01-15 15:00:00&#x22;)',
    required: false,
  },
  past_minutes_start: {
    description: 'Start of relative time range (older boundary)',
    type: 'number',
    typeDescription: 'Minutes ago from now. Must be greater than past_minutes_end.',
    required: false,
  },
  past_minutes_end: {
    description: 'End of relative time range (newer boundary)',
    type: 'number',
    typeDescription: 'Minutes ago from now. Must be less than past_minutes_start.',
    required: false,
  },
}"
/>

**Note:** You must provide either:

* All three date parameters (`start_date`, `end_date`, `time_zone`), OR
* All three exact datetime parameters (`start_datetime`, `end_datetime`, `time_zone`), OR
* Both relative parameters (`past_minutes_start`, `past_minutes_end`)

#### Examples [#examples]

**Date-based query (last 30 days):**

```
?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York
```

**Exact datetime query (8 AM to 10 AM in New York on Jan 15, sent as UTC):**

```
?start_datetime=2024-01-15%2013:00:00&end_datetime=2024-01-15%2015:00:00&time_zone=America/New_York
```

**Relative query (last 60 minutes):**

```
?past_minutes_start=60&past_minutes_end=0
```

### Filter Parameters [#filter-parameters]

The `filters` parameter accepts a JSON-encoded array of filter objects to narrow down your data.

You can also pass `segment_id`, the ID of a [saved segment](/docs/segments), instead of or alongside `filters`. The segment's filters are expanded on the server and ANDed with any `filters` you pass. Use the [Segments endpoints](/docs/api/segments/list) to find IDs. Public and private-link callers can only use segments marked as shown on the public dashboard.

```
?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC&segment_id=12
```

#### Filter Object Structure [#filter-object-structure]

<TypeTable
  type="{
  parameter: {
    description: 'The dimension to filter on',
    type: 'FilterParameter',
    typeDescription: 'See Filter Parameters table below',
    required: true,
  },
  type: {
    description: 'The type of comparison to perform',
    type: 'FilterType',
    typeDescription: '&#x22;equals&#x22; | &#x22;not_equals&#x22; | &#x22;contains&#x22; | &#x22;not_contains&#x22; | &#x22;regex&#x22; | &#x22;not_regex&#x22; | &#x22;greater_than&#x22; | &#x22;less_than&#x22;',
    required: true,
  },
  value: {
    description: 'Array of values to match against',
    type: 'Array<string | number>',
    typeDescription: 'Multiple values are treated as OR conditions',
    required: true,
  },
}"
/>

#### Filter Types [#filter-types]

<TypeTable
  type="{
  equals: {
    description: 'Exact match',
    type: 'string',
    typeDescription: 'Value must exactly match',
  },
  not_equals: {
    description: 'Exclude exact matches',
    type: 'string',
    typeDescription: 'Value must not match',
  },
  contains: {
    description: 'Substring match',
    type: 'string',
    typeDescription: 'Value must contain the substring (uses SQL LIKE %value%)',
  },
  not_contains: {
    description: 'Exclude substring matches',
    type: 'string',
    typeDescription: 'Value must not contain the substring',
  },
  regex: {
    description: 'Regular expression match',
    type: 'string',
    typeDescription: 'Value must match the regex pattern (max 500 characters)',
  },
  not_regex: {
    description: 'Exclude regex matches',
    type: 'string',
    typeDescription: 'Value must not match the regex pattern',
  },
  greater_than: {
    description: 'Numeric greater than',
    type: 'number',
    typeDescription: 'For numeric fields like lat, lon',
  },
  less_than: {
    description: 'Numeric less than',
    type: 'number',
    typeDescription: 'For numeric fields like lat, lon',
  },
}"
/>

#### Available Filter Parameters [#available-filter-parameters]

**Browser & Device**

<TypeTable
  type="{
  browser: {
    description: 'Browser name',
    type: 'string',
    typeDescription: 'e.g., &#x22;Chrome&#x22;, &#x22;Firefox&#x22;, &#x22;Safari&#x22;',
  },
  browser_version: {
    description: 'Browser with version',
    type: 'string',
    typeDescription: 'e.g., &#x22;Chrome 120&#x22;',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
    typeDescription: 'e.g., &#x22;Windows&#x22;, &#x22;macOS&#x22;, &#x22;Linux&#x22;',
  },
  operating_system_version: {
    description: 'OS with version',
    type: 'string',
    typeDescription: 'e.g., &#x22;Windows 10/11&#x22;, &#x22;macOS 14&#x22;',
  },
  device_type: {
    description: 'Device category',
    type: 'string',
    typeDescription: '&#x22;desktop&#x22;, &#x22;mobile&#x22;, &#x22;tablet&#x22;',
  },
  dimensions: {
    description: 'Screen dimensions',
    type: 'string',
    typeDescription: 'e.g., &#x22;1920x1080&#x22;, &#x22;390x844&#x22;',
  },
  language: {
    description: 'Browser language',
    type: 'string',
    typeDescription: 'e.g., &#x22;en-US&#x22;, &#x22;es-ES&#x22;',
  },
}"
/>

**Location**

<TypeTable
  type="{
  country: {
    description: 'Country code',
    type: 'string',
    typeDescription: 'ISO 3166-1 alpha-2 code, e.g., &#x22;US&#x22;, &#x22;GB&#x22;',
  },
  region: {
    description: 'Geographic region/state',
    type: 'string',
    typeDescription: 'e.g., &#x22;California&#x22;, &#x22;England&#x22;',
  },
  city: {
    description: 'City name with region prefix',
    type: 'string',
    typeDescription: 'Format: &#x22;Region-City&#x22;, e.g., &#x22;CA-San Francisco&#x22;',
  },
  timezone: {
    description: 'User timezone',
    type: 'string',
    typeDescription: 'IANA timezone, e.g., &#x22;America/New_York&#x22;',
  },
  lat: {
    description: 'Latitude',
    type: 'number',
    typeDescription: 'Supports greater_than, less_than, equals (with 0.001 tolerance)',
  },
  lon: {
    description: 'Longitude',
    type: 'number',
    typeDescription: 'Supports greater_than, less_than, equals (with 0.001 tolerance)',
  },
}"
/>

**Page & Traffic**

<TypeTable
  type="{
  pathname: {
    description: 'URL pathname',
    type: 'string',
    typeDescription: 'e.g., &#x22;/blog/post-title&#x22;',
  },
  page_title: {
    description: 'HTML page title',
    type: 'string',
  },
  hostname: {
    description: 'Website hostname',
    type: 'string',
    typeDescription: 'e.g., &#x22;example.com&#x22;',
  },
  querystring: {
    description: 'URL query string',
    type: 'string',
    typeDescription: 'e.g., &#x22;?ref=twitter&#x22;',
  },
  referrer: {
    description: 'Referrer domain (without www)',
    type: 'string',
    typeDescription: 'e.g., &#x22;google.com&#x22;, &#x22;twitter.com&#x22;',
  },
  entry_page: {
    description: 'First page in session (landing page)',
    type: 'string',
  },
  exit_page: {
    description: 'Last page in session',
    type: 'string',
  },
  channel: {
    description: 'Marketing channel',
    type: 'string',
    typeDescription: 'e.g., &#x22;Direct&#x22;, &#x22;Organic Search&#x22;, &#x22;Social&#x22;',
  },
}"
/>

**UTM Parameters**

<TypeTable
  type="{
  utm_source: {
    description: 'UTM source parameter',
    type: 'string',
    typeDescription: 'e.g., &#x22;google&#x22;, &#x22;newsletter&#x22;',
  },
  utm_medium: {
    description: 'UTM medium parameter',
    type: 'string',
    typeDescription: 'e.g., &#x22;cpc&#x22;, &#x22;email&#x22;',
  },
  utm_campaign: {
    description: 'UTM campaign parameter',
    type: 'string',
  },
  utm_term: {
    description: 'UTM term parameter',
    type: 'string',
  },
  utm_content: {
    description: 'UTM content parameter',
    type: 'string',
  },
}"
/>

**User & Events**

<TypeTable
  type="{
  user_id: {
    description: 'User identifier',
    type: 'string',
    typeDescription: 'Matches both device fingerprint and custom identified user ID',
  },
  event_name: {
    description: 'Custom event name',
    type: 'string',
    typeDescription: 'Filters to sessions containing the event',
  },
}"
/>

#### Filter Examples [#filter-examples]

<Tabs items="['Single Filter', 'Multiple Filters', 'Contains', 'Regex', 'Numeric', 'URL-encoded']">
  <Tab value="Single Filter">
    ```json
    [
      {
        "parameter": "country",
        "type": "equals",
        "value": ["US"]
      }
    ]
    ```
  </Tab>

  <Tab value="Multiple Filters">
    Multiple filters use AND logic:

    ```json
    [
      {
        "parameter": "country",
        "type": "equals",
        "value": ["US", "CA"]
      },
      {
        "parameter": "device_type",
        "type": "equals",
        "value": ["mobile"]
      }
    ]
    ```
  </Tab>

  <Tab value="Contains">
    Substring match:

    ```json
    [
      {
        "parameter": "pathname",
        "type": "contains",
        "value": ["/blog"]
      }
    ]
    ```
  </Tab>

  <Tab value="Regex">
    Pattern match:

    ```json
    [
      {
        "parameter": "pathname",
        "type": "regex",
        "value": ["^/products/[0-9]+$"]
      }
    ]
    ```
  </Tab>

  <Tab value="Numeric">
    Geolocation comparison:

    ```json
    [
      {
        "parameter": "lat",
        "type": "greater_than",
        "value": ["37.0"]
      },
      {
        "parameter": "lat",
        "type": "less_than",
        "value": ["38.0"]
      }
    ]
    ```
  </Tab>

  <Tab value="URL-encoded">
    ```
    ?filters=%5B%7B%22parameter%22%3A%22country%22%2C%22type%22%3A%22equals%22%2C%22value%22%3A%5B%22US%22%5D%7D%5D
    ```
  </Tab>
</Tabs>

***

## Error Responses [#error-responses]

All endpoints return standard HTTP status codes:

* **200** - Success
* **400** - Bad Request (invalid parameters)
* **401** - Unauthorized (missing or invalid API key)
* **403** - Forbidden (no access to site)
* **404** - Not Found (site doesn't exist)
* **429** - Too Many Requests (rate limit exceeded)
* **500** - Internal Server Error

### Error Response Format [#error-response-format]

```json
{
  "error": "Error message describing what went wrong"
}
```


# Build a Live Visitor Feed (/de/docs/api/live-feed)





Rybbit doesn't push a websocket stream, but the events endpoint is built for polling: pass a `since_timestamp` and you get only the events that happened after it. This guide builds a self-advancing feed loop you can wire into a dashboard, a terminal ticker, or an alerting rule.

**Endpoints used:**

* [`GET /live-user-count`](/docs/api/overview/live-visitors) — how many visitors are active right now
* [`GET /events`](/docs/api/events/list) — the event stream, polled incrementally

## How incremental polling works [#how-incremental-polling-works]

The events endpoint returns the newest events first. To stream without duplicates, remember the timestamp of the most recent event you've seen and send it as `since_timestamp` on the next request — the API returns only events newer than that, up to 500 per call.

<Steps>
  <Step>
    **Fetch the initial batch** to establish a starting watermark (the newest timestamp).
  </Step>

  <Step>
    **On an interval, request events `since_timestamp`** = your watermark.
  </Step>

  <Step>
    **Process the new events** (print, render, alert) and advance the watermark to the newest one returned.
  </Step>
</Steps>

<Callout type="info">
  `since_timestamp` returns up to **500** events per call. If you expect more than 500 events between polls (a very high-traffic site with a long interval), poll more frequently so each batch stays under the cap.
</Callout>

## Full script [#full-script]

A Node script that prints a live count plus a rolling feed of activity. The same loop drives a browser dashboard — just replace `console.log` with DOM updates.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="live-feed.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const POLL_MS = 10000; // every 10 seconds

    async function get(path, params = {}) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    async function liveCount() {
      const { count } = await get('/live-user-count', { minutes: 5 });
      return count;
    }

    function describe(e) {
      const where = e.city ? `${e.city}, ${e.country}` : e.country || 'Unknown';
      if (e.type === 'pageview')     return `👀 viewed ${e.pathname} — ${where}`;
      if (e.type === 'custom_event') return `⚡ ${e.event_name} (${e.pathname}) — ${where}`;
      if (e.type === 'outbound')     return `↗️  left via ${e.pathname} — ${where}`;
      return `• ${e.type} — ${where}`;
    }

    let watermark = null; // ISO timestamp of the newest event we've shown

    async function poll() {
      try {
        const params = watermark ? { since_timestamp: watermark } : { page_size: 20 };
        const [{ data: events }, count] = await Promise.all([get('/events', params), liveCount()]);

        // Events come back newest-first; show oldest-first so the feed reads top-to-bottom
        for (const e of [...events].reverse()) {
          console.log(`[${new Date(e.timestamp).toLocaleTimeString()}] ${describe(e)}`);
        }
        if (events.length) watermark = events[0].timestamp; // newest event becomes the new watermark

        process.stdout.write(`\n🟢 ${count} visitors online\n`);
      } catch (err) {
        console.error('poll error:', err.message);
      }
    }

    console.log('Starting live feed… (Ctrl+C to stop)');
    poll();
    setInterval(poll, POLL_MS);
    ```
  </Tab>

  <Tab value="Python">
    ```python title="live_feed.py"
    import os, time
    from datetime import datetime
    import requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    POLL_SECONDS = 10

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def get(path, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def live_count():
        return get("/live-user-count", minutes=5)["count"]


    def describe(e):
        where = f'{e["city"]}, {e["country"]}' if e.get("city") else e.get("country") or "Unknown"
        if e["type"] == "pageview":
            return f'👀 viewed {e["pathname"]} — {where}'
        if e["type"] == "custom_event":
            return f'⚡ {e["event_name"]} ({e["pathname"]}) — {where}'
        if e["type"] == "outbound":
            return f'↗️  left via {e["pathname"]} — {where}'
        return f'• {e["type"]} — {where}'


    watermark = None  # ISO timestamp of the newest event we've shown

    print("Starting live feed… (Ctrl+C to stop)")
    while True:
        try:
            params = {"since_timestamp": watermark} if watermark else {"page_size": 20}
            events = get("/events", **params)["data"]

            # Events come back newest-first; show oldest-first so the feed reads top-to-bottom
            for e in reversed(events):
                ts = datetime.fromisoformat(e["timestamp"].replace("Z", "+00:00")).strftime("%H:%M:%S")
                print(f"[{ts}] {describe(e)}")
            if events:
                watermark = events[0]["timestamp"]  # newest event becomes the new watermark

            print(f"\n🟢 {live_count()} visitors online\n")
        except Exception as err:
            print(f"poll error: {err}")
        time.sleep(POLL_SECONDS)
    ```
  </Tab>
</Tabs>

## Example output [#example-output]

```text
Starting live feed… (Ctrl+C to stop)
[14:22:01] 👀 viewed /pricing — San Francisco, US
[14:22:03] ⚡ signup (/signup) — London, GB
[14:22:05] ↗️  left via /docs — Berlin, DE

🟢 42 visitors online
```

## Turn it into an alert [#turn-it-into-an-alert]

Because each poll hands you the raw events, you can act on them instead of just printing. For example, ping a channel whenever someone hits your enterprise pricing page:

<Tabs items="['JavaScript']">
  <Tab value="JavaScript">
    ```javascript title="React to specific events"
    for (const e of events) {
      if (e.type === 'pageview' && e.pathname === '/enterprise') {
        await fetch(process.env.SLACK_WEBHOOK, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            text: `🏢 Enterprise page visit from ${e.city || e.country} (${e.referrer || 'direct'})`,
          }),
        });
      }
    }
    ```
  </Tab>
</Tabs>

<Callout type="warn">
  **Mind the daily quota.** On Rybbit Cloud, a continuous poll is measured against your plan's daily quota (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only)), not just its per-second rate. A 10-second poll running around the clock is 8,640 requests/day — over the Standard quota of 5,000, and 17,280 with the live-count call added. Poll every 20-30 seconds, or only while someone is actually watching the page, and check `X-RateLimit-Daily-Remaining` to see where you stand. Self-hosted instances are not rate limited.
</Callout>

## Next steps [#next-steps]

* [Events API reference](/docs/api/events/list) — full event object fields, plus `before_timestamp` for scrolling backwards through history.
* [Export Raw Events to Your Warehouse](/docs/api/export-events) — the same `since_timestamp` mechanism, used for durable incremental syncs instead of a live view.


# Sending Events (/de/docs/api/sending-events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/track
    ```

    Track pageviews, custom events, performance, and errors from server-side applications, mobile apps, or any platform. An API key is optional but recommended for server-side tracking — it bypasses bot detection and domain validation. IP addresses are resolved to geolocation and user agents are parsed for browser/OS/device info.

    ### Request Body [#request-body]

    All parameters are sent in the request body as JSON.

    <TypeTable
      type="{
  site_id: {
    description: 'Your site ID',
    type: 'string',
    required: true,
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;performance&#x22; | &#x22;outbound&#x22; | &#x22;error&#x22;',
    default: 'pageview',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  hostname: {
    description: 'Domain name',
    type: 'string',
    typeDescription: 'Max 253 chars',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
    typeDescription: 'Max 512 chars',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  user_id: {
    description: 'Custom user identifier',
    type: 'string',
    typeDescription: 'Max 255 chars',
  },
  user_agent: {
    description: 'Custom user agent string - will be parsed for browser/OS/device info',
    type: 'string',
    typeDescription: 'Max 512 chars',
  },
  ip_address: {
    description: 'Custom IP for geolocation - will be resolved to location data',
    type: 'string',
    typeDescription: 'Valid IPv4 or IPv6 address',
  },
  querystring: {
    description: 'Query parameters',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  language: {
    description: 'Language code',
    type: 'string',
    typeDescription: 'e.g., &#x22;en&#x22;, &#x22;es&#x22;, &#x22;fr&#x22;',
  },
  screenWidth: {
    description: 'Screen width in logical pixels (density-independent pixels)',
    type: 'number',
  },
  screenHeight: {
    description: 'Screen height in logical pixels (density-independent pixels)',
    type: 'number',
  },
  event_name: {
    description: 'Event name (required for custom events)',
    type: 'string',
    typeDescription: 'Max 256 chars',
  },
  properties: {
    description: 'JSON string with event data (for custom events, outbound, error)',
    type: 'string',
    typeDescription: 'Max 2048 chars (4096 for error events)',
  },
  feature_flags: {
    description: 'Optional map of feature flag keys to assigned values. Useful for server-side flag evaluation and filtering analytics by flag value.',
    type: 'Record<string, string>',
    typeDescription: 'Keys max 100 chars, values max 2048 chars',
  },
}"
    />

    #### Pageview [#pageview]

    Standard page view tracking. Set `type: "pageview"` (default).

    #### Custom Event [#custom-event]

    Track custom events with optional properties. Set `type: "custom_event"`.

    <TypeTable
      type="{
  event_name: {
    description: 'Name of the custom event',
    type: 'string',
    typeDescription: 'Max 256 chars',
    required: true,
  },
  properties: {
    description: 'Event data as JSON string',
    type: 'string',
    typeDescription: 'Valid JSON, max 2048 chars',
  },
}"
    />

    #### Performance [#performance]

    Track Core Web Vitals. Set `type: "performance"`.

    <TypeTable
      type="{
  lcp: {
    description: 'Largest Contentful Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  cls: {
    description: 'Cumulative Layout Shift score',
    type: 'number',
    typeDescription: 'nullable, typically 0-1',
  },
  inp: {
    description: 'Interaction to Next Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  fcp: {
    description: 'First Contentful Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  ttfb: {
    description: 'Time to First Byte in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
}"
    />

    #### Outbound [#outbound]

    Track outbound link clicks. Set `type: "outbound"`. Pass details in the `properties` JSON string.

    <TypeTable
      type="{
  url: {
    description: 'Destination URL',
    type: 'string',
    required: true,
  },
  text: {
    description: 'Link text content',
    type: 'string',
  },
  target: {
    description: 'Link target attribute',
    type: 'string',
    typeDescription: 'e.g., &#x22;_blank&#x22;, &#x22;_self&#x22;',
  },
}"
    />

    #### Error [#error]

    Track JavaScript errors. Set `type: "error"`. `event_name` is the error type and `properties` carries the error details as a JSON string.

    <TypeTable
      type="{
  message: {
    description: 'Error message',
    type: 'string',
    typeDescription: 'Max 500 chars',
    required: true,
  },
  stack: {
    description: 'Stack trace',
    type: 'string',
    typeDescription: 'Max 2000 chars',
  },
  fileName: {
    description: 'File where error occurred',
    type: 'string',
  },
  lineNumber: {
    description: 'Line number',
    type: 'number',
  },
  columnNumber: {
    description: 'Column number',
    type: 'number',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the event was accepted',
    type: 'boolean',
  },
}"
    />

    ### Rate Limiting [#rate-limiting]

    API keys are limited to **500 requests per 10 minutes**. Exceeding the limit returns a `429` status code.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/track" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "site_id": "1",
            "type": "custom_event",
            "pathname": "/checkout",
            "event_name": "purchase",
            "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch('https://app.rybbit.io/api/track', {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer your_api_key_here',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            site_id: '1',
            type: 'custom_event',
            pathname: '/checkout',
            event_name: 'purchase',
            properties: JSON.stringify({ amount: 99.99, currency: 'USD' })
          })
        });

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests
        import json

        response = requests.post(
            'https://app.rybbit.io/api/track',
            json={
                'site_id': '1',
                'type': 'custom_event',
                'pathname': '/checkout',
                'event_name': 'purchase',
                'properties': json.dumps({'amount': 99.99, 'currency': 'USD'})
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'site_id' => '1',
            'type' => 'custom_event',
            'pathname' => '/checkout',
            'event_name' => 'purchase',
            'properties' => json_encode(['amount' => 99.99, 'currency' => 'USD'])
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/track');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/track')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          site_id: '1',
          type: 'custom_event',
          pathname: '/checkout',
          event_name: 'purchase',
          properties: { amount: 99.99, currency: 'USD' }.to_json
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "site_id":    "1",
            "type":       "custom_event",
            "pathname":   "/checkout",
            "event_name": "purchase",
            "properties": `{"amount": 99.99, "currency": "USD"}`,
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/track", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "site_id": "1",
            "type": "custom_event",
            "pathname": "/checkout",
            "event_name": "purchase",
            "properties": r#"{"amount": 99.99, "currency": "USD"}"#
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/track")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "site_id": "1",
          "type": "custom_event",
          "pathname": "/checkout",
          "event_name": "purchase",
          "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/track"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            site_id = "1",
            type = "custom_event",
            pathname = "/checkout",
            event_name = "purchase",
            properties = JsonSerializer.Serialize(new { amount = 99.99, currency = "USD" })
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/track", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Success"
    {
      "success": true
    }
    ```

    ```json title="Error"
    {
      "success": false,
      "error": "Invalid payload",
      "details": {
        "fieldErrors": {},
        "formErrors": ["Custom events require event_name"]
      }
    }
    ```
  </div>
</div>


# Automated Weekly Report (/de/docs/api/weekly-report)





This guide builds a script you can run on a schedule (a cron job, GitHub Action, or serverless function) that pulls last week's numbers, compares them to the week before, and posts a digest to Slack, email, or anywhere else.

**Endpoints used:**

* [`GET /overview`](/docs/api/overview/overview) — headline metrics for a date range
* [`GET /metric`](/docs/api/overview/metric) — top pages and traffic sources

<Callout type="info">
  Every analytics endpoint takes the same [time parameters](/docs/api/getting-started#time-parameters). The trick behind any comparison report is simply calling the same endpoint twice with two adjacent date ranges.
</Callout>

## The workflow [#the-workflow]

<Steps>
  <Step>
    **Fetch this week's overview** for the last 7 days.
  </Step>

  <Step>
    **Fetch last week's overview** for the 7 days before that, so you can compute the change.
  </Step>

  <Step>
    **Fetch top pages and top sources** from the `metric` endpoint to add context.
  </Step>

  <Step>
    **Format and deliver** the digest.
  </Step>
</Steps>

## Full script [#full-script]

This example posts a formatted message to a Slack incoming webhook, but the `buildReport` function returns plain data you can route anywhere.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="weekly-report.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const SLACK_WEBHOOK = process.env.SLACK_WEBHOOK;
    const TZ = 'America/New_York';

    // Helper: format a Date as YYYY-MM-DD
    const ymd = (d) => d.toISOString().slice(0, 10);

    async function get(path, params) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${API_KEY}` },
      });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    async function overview(start, end) {
      const { data } = await get('/overview', {
        start_date: ymd(start),
        end_date: ymd(end),
        time_zone: TZ,
      });
      return data;
    }

    async function topMetric(parameter, start, end, limit = 5) {
      const { data } = await get('/metric', {
        parameter,
        start_date: ymd(start),
        end_date: ymd(end),
        time_zone: TZ,
        limit,
      });
      return data.data; // metric nests results under data.data
    }

    function pctChange(current, previous) {
      if (!previous) return null;
      return ((current - previous) / previous) * 100;
    }

    async function buildReport() {
      const now = new Date();
      const thisWeekStart = new Date(now); thisWeekStart.setDate(now.getDate() - 7);
      const lastWeekEnd   = new Date(now); lastWeekEnd.setDate(now.getDate() - 8);
      const lastWeekStart = new Date(now); lastWeekStart.setDate(now.getDate() - 14);

      const [thisWeek, lastWeek, topPages, topSources] = await Promise.all([
        overview(thisWeekStart, now),
        overview(lastWeekStart, lastWeekEnd),
        topMetric('pathname', thisWeekStart, now),
        topMetric('referrer', thisWeekStart, now),
      ]);

      return {
        sessions: { value: thisWeek.sessions, change: pctChange(thisWeek.sessions, lastWeek.sessions) },
        users:    { value: thisWeek.users,    change: pctChange(thisWeek.users, lastWeek.users) },
        pageviews:{ value: thisWeek.pageviews, change: pctChange(thisWeek.pageviews, lastWeek.pageviews) },
        bounceRate: thisWeek.bounce_rate,
        topPages,
        topSources,
      };
    }

    function arrow(change) {
      if (change === null) return '';
      const sign = change >= 0 ? '▲' : '▼';
      return ` ${sign} ${Math.abs(change).toFixed(1)}%`;
    }

    async function postToSlack(r) {
      const lines = [
        `*📊 Weekly Analytics Report*`,
        ``,
        `• Sessions: *${r.sessions.value.toLocaleString()}*${arrow(r.sessions.change)}`,
        `• Unique users: *${r.users.value.toLocaleString()}*${arrow(r.users.change)}`,
        `• Pageviews: *${r.pageviews.value.toLocaleString()}*${arrow(r.pageviews.change)}`,
        `• Bounce rate: *${r.bounceRate.toFixed(1)}%*`,
        ``,
        `*Top pages*`,
        ...r.topPages.map((p) => `   ${p.value} — ${p.count.toLocaleString()}`),
        ``,
        `*Top sources*`,
        ...r.topSources.map((s) => `   ${s.value || 'Direct'} — ${s.count.toLocaleString()}`),
      ];
      await fetch(SLACK_WEBHOOK, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text: lines.join('\n') }),
      });
    }

    buildReport().then(postToSlack).catch(console.error);
    ```
  </Tab>

  <Tab value="Python">
    ```python title="weekly_report.py"
    import os
    from datetime import datetime, timedelta
    import requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    SLACK_WEBHOOK = os.environ["SLACK_WEBHOOK"]
    TZ = "America/New_York"

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def ymd(d: datetime) -> str:
        return d.strftime("%Y-%m-%d")


    def get(path: str, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def overview(start, end):
        return get("/overview", start_date=ymd(start), end_date=ymd(end), time_zone=TZ)["data"]


    def top_metric(parameter, start, end, limit=5):
        # metric nests results under data.data
        return get("/metric", parameter=parameter, start_date=ymd(start),
                   end_date=ymd(end), time_zone=TZ, limit=limit)["data"]["data"]


    def pct_change(current, previous):
        return None if not previous else (current - previous) / previous * 100


    def build_report():
        now = datetime.utcnow()
        this_start = now - timedelta(days=7)
        last_end = now - timedelta(days=8)
        last_start = now - timedelta(days=14)

        this_week = overview(this_start, now)
        last_week = overview(last_start, last_end)

        return {
            "sessions": (this_week["sessions"], pct_change(this_week["sessions"], last_week["sessions"])),
            "users": (this_week["users"], pct_change(this_week["users"], last_week["users"])),
            "pageviews": (this_week["pageviews"], pct_change(this_week["pageviews"], last_week["pageviews"])),
            "bounce_rate": this_week["bounce_rate"],
            "top_pages": top_metric("pathname", this_start, now),
            "top_sources": top_metric("referrer", this_start, now),
        }


    def arrow(change):
        if change is None:
            return ""
        return f" {'▲' if change >= 0 else '▼'} {abs(change):.1f}%"


    def post_to_slack(r):
        lines = [
            "*📊 Weekly Analytics Report*", "",
            f"• Sessions: *{r['sessions'][0]:,}*{arrow(r['sessions'][1])}",
            f"• Unique users: *{r['users'][0]:,}*{arrow(r['users'][1])}",
            f"• Pageviews: *{r['pageviews'][0]:,}*{arrow(r['pageviews'][1])}",
            f"• Bounce rate: *{r['bounce_rate']:.1f}%*", "",
            "*Top pages*",
            *[f"   {p['value']} — {p['count']:,}" for p in r["top_pages"]], "",
            "*Top sources*",
            *[f"   {s['value'] or 'Direct'} — {s['count']:,}" for s in r["top_sources"]],
        ]
        requests.post(SLACK_WEBHOOK, json={"text": "\n".join(lines)})


    post_to_slack(build_report())
    ```
  </Tab>
</Tabs>

## Example output [#example-output]

```text
📊 Weekly Analytics Report

• Sessions: 15,420 ▲ 12.3%
• Unique users: 12,847 ▲ 9.8%
• Pageviews: 48,933 ▼ 2.1%
• Bounce rate: 42.8%

Top pages
   / — 8,230
   /pricing — 3,120
   /blog/getting-started — 1,940

Top sources
   google.com — 6,410
   Direct — 4,220
   twitter.com — 1,180
```

## Schedule it [#schedule-it]

Run the script every Monday morning with cron:

```bash title="crontab -e"
# Every Monday at 9:00 AM
0 9 * * 1 RYBBIT_API_KEY=xxx SLACK_WEBHOOK=https://hooks.slack.com/... node /path/to/weekly-report.js
```

<Callout type="info">
  **Want a richer report?** The same pattern extends naturally. Add `topMetric('channel', ...)` for marketing channels, `topMetric('country', ...)` for geography, or call the [`time-series` endpoint](/docs/api/overview/time-series) with `bucket=day` to attach a 7-point trend line.
</Callout>

## Next steps [#next-steps]

* [Compare Marketing Channel Performance](/docs/api/channel-performance) — go beyond traffic counts and rank sources by how well they convert.
* [Export Raw Events to Your Warehouse](/docs/api/export-events) — if you'd rather build reports in your own BI tool.


# Dashboard Embed (/de/docs/embeds/dashboard)





The dashboard embed lets you place the main Rybbit analytics dashboard on another site with a self-contained iframe. Dashboard embeds use private-link routes with `embed=true`.

## Try It Out [#try-it-out]

Configure the private-link dashboard embed URL below. The generated snippet uses the same private-link route created in the Rybbit dashboard.

<DashboardEmbedDemo />

## Requirements [#requirements]

Dashboard embeds require a generated private link. The private link key is included in the route, for example `/{siteId}/{privateLinkKey}/main`.

Unlike [Widget Embeds](/docs/embeds/widget), dashboard embeds expose the full read-only analytics dashboard, not just the compact live visitor widget.

<Callout type="warn">
  Private links are not listed publicly, but anyone with the private link can view the dashboard. Treat the iframe URL like a shareable read-only secret.
</Callout>

## Setup [#setup]

1. Open your site in the Rybbit dashboard and click the settings icon.
2. Go to the **Dashboard Embed** tab.
3. Generate a private link if one does not already exist.
4. Choose the embed theme: light, dark, or system.
5. Choose whether to hide the dashboard sidebar.
6. Copy the generated `<iframe>` snippet and paste it anywhere on your site.

## Appearance [#appearance]

* **Theme**: `light`, `dark`, or `system`. `system` follows the viewer's operating system color-scheme preference.
* **Hide sidebar**: removes the dashboard sidebar and keeps viewers on the main dashboard page.
* **Footer**: the Rybbit footer is hidden automatically in embed mode.

## Example [#example]

```html
<iframe
  src="https://app.rybbit.io/YOUR_SITE_ID/YOUR_PRIVATE_LINK_KEY/main?embed=true&theme=system&hideSidebar=true"
  style="border: 0; width: 100%; height: 720px;"
  loading="lazy"
  title="Analytics dashboard"
></iframe>
```

If you self-host Rybbit, replace `app.rybbit.io` with your own domain.

## URL Parameters [#url-parameters]

| Parameter     | Values                    | Description                                                               |
| ------------- | ------------------------- | ------------------------------------------------------------------------- |
| `embed`       | `true`                    | Enables embed mode                                                        |
| `theme`       | `light`, `dark`, `system` | Sets the embedded dashboard color scheme. Defaults to `system`            |
| `hideSidebar` | `true`, `false`           | Hides the dashboard sidebar and keeps visitors on the main dashboard page |

When `hideSidebar=true`, only the main dashboard page is shown in the iframe. Leave it off if you want viewers to use the dashboard sidebar to navigate other analytics pages allowed by the private link.

The private key is part of the path, not a query parameter: `/{siteId}/{privateLinkKey}/main?embed=true`.


# Widget Embeds (/de/docs/embeds/widget)





Widget Embeds let you place a compact live visitor widget on another site with a self-contained iframe. There is no script tag, no JavaScript on your site, and no dependency on the Rybbit tracking script.

## Try It [#try-it]

Configure the widget below to see how it'll look. The preview shows live data from [demo.rybbit.com](https://demo.rybbit.com).

<EmbedWidgetDemo />

## Requirements [#requirements]

The widget needs a public read-only data endpoint, so you must enable **Widget Embeds** on the site. This is separate from **Public Analytics**. Turning it on only exposes the live count, time series, and top countries to the widget endpoint, not your full dashboard.

<Callout type="info">
  Enabling Widget Embeds does **not** make your dashboard public. Only the data shown in the widget itself (visitor count, per-minute / per-hour / per-day series, top 5 countries) is accessible; no individual sessions, events, pages, or referrers are exposed.
</Callout>

## Setup [#setup]

1. Open your site in the Rybbit dashboard and click the settings icon.
2. Go to the **Widget Embeds** tab.
3. Toggle **Widget Enabled** on.
4. Pick your options: variant, time window, theme, accent color, and display settings.
5. Copy the generated `<iframe>` snippet and paste it anywhere on your site.

## Variants [#variants]

### Card [#card]

A self-contained dashboard card showing the live count, an optional bar chart of users over time, and an optional list of top countries.

| Option        | Values                         | Default | Description                                              |
| ------------- | ------------------------------ | ------- | -------------------------------------------------------- |
| Time window   | 30 minutes / 24 hours / 7 days | 30 min  | Window the count and chart cover                         |
| Bar chart     | on / off                       | on      | Show a bar chart bucketed per minute / hour / day        |
| Top countries | on / off                       | on      | List the top 5 countries in the window                   |
| Width         | 240-800 px                     | 360 px  | Iframe width; use `max-width: 100%` for responsive sites |

### Inline Pill [#inline-pill]

A compact pill that fits inline with your site's chrome, such as in a header or footer. It shows the pulsing dot, the live count over the last 30 minutes, and the Rybbit logo.

## Appearance [#appearance]

* **Theme**: `dark` or `light`. The widget background is transparent, so rounded-corner edges blend into whatever sits behind the iframe.
* **Accent color**: any hex color. Used for the pulsing live-indicator dot and the bar-chart bars. Defaults to Rybbit emerald.

## Example [#example]

```html
<iframe
  src="https://app.rybbit.io/widget/YOUR_SITE_ID?variant=card&theme=dark&minutes=30&chart=true&countries=true"
  style="border: 0; width: 360px; height: 390px; max-width: 100%;"
  loading="lazy"
  title="Live visitors"
></iframe>
```

If you self-host Rybbit, replace `app.rybbit.io` with your own domain.

## URL Parameters [#url-parameters]

You don't usually need to build the URL by hand because the dashboard generates the snippet for you, but the widget URL accepts these parameters:

| Parameter   | Values                                 | Description                               |
| ----------- | -------------------------------------- | ----------------------------------------- |
| `variant`   | `card`, `inline`                       | Layout variant                            |
| `theme`     | `dark`, `light`                        | Color scheme                              |
| `accent`    | 6-character hex, no `#`, e.g. `10b981` | Pulse / bar color                         |
| `minutes`   | `30`, `1440`, `10080`                  | Time window in minutes, card variant only |
| `chart`     | `true`, `false`                        | Show the bar chart, card variant only     |
| `countries` | `true`, `false`                        | Show top countries, card variant only     |

## Caching [#caching]

The widget HTML and the underlying stats endpoint are both cached for 60 seconds on the server, so embedding the widget on a high-traffic page won't put pressure on your Rybbit instance. The visible count refreshes once per minute.


# Errors (/de/docs/feature-guides/errors)



The Errors tab shows JavaScript errors occurring on your website, helping you identify and fix bugs that affect user experience.

## Enabling Error Tracking [#enabling-error-tracking]

Enable error tracking in your [site settings](/docs/site-settings).

## Error Information [#error-information]

For each error, you'll see:

* **Error Type** - ReferenceError, TypeError, SyntaxError, NetworkError, etc.
* **Error Message** - The specific error message
* **Stack Trace** - The chain of function calls that led to the error
* **Affected Sessions** - Number of unique sessions in which this error occurred
* **Occurrence Count** - How many times the error was triggered
  Expanding an error shows its individual occurrences, including the timestamp and page for each event.
* **Browser & Device** - Which environments experience this error

## Using Error Data [#using-error-data]

* **Prioritize by impact** - Fix errors affecting the most users first
* **Monitor after deployments** - Watch for new errors after releasing code
* **Debug user reports** - Find the exact technical issue when users report problems
* **Track third-party issues** - Identify when external integrations are malfunctioning


# Events (/de/docs/feature-guides/events)



The Events tab shows custom events tracked on your website.

## Setting Up Events [#setting-up-events]

See the [Track Events guide](/docs/track-events) for implementation details.

## Events Page [#events-page]

The events page includes:

* **Events Chart** - Visualize event trends over time
* **Event Log** - Recent individual event occurrences (click any row to open a details sheet)

The **Custom Events List** — all tracked events with counts — lives in the Events section of the main dashboard.

## Event Metrics [#event-metrics]

For each event in the Custom Events List:

* **Event Name** - The name you assigned to the event
* **Count** - Total times triggered in the selected period
* **Percentage** - Share of total events

## Event Properties [#event-properties]

In the Custom Events List, click the expand arrow on any event to view its properties. Properties show the key-value pairs attached to events, helping you understand event context (e.g., which product was purchased, what button was clicked).

## Filtering [#filtering]

* Click any event name to filter the dashboard to sessions containing that event
* Use the filter panel to combine event filters with other dimensions
* Filter by time range to analyze event trends


# Globe (/de/docs/feature-guides/globe)



The Globe tab shows where your visitors connect from on an interactive map.

## View Modes [#view-modes]

### 2D Map [#2d-map]

* **Timeline** - View sessions by timeframe, click individual sessions for details
* **Coordinates** - Sessions as dots with color intensity showing traffic volume
* **Countries** - Countries highlighted by traffic volume
* **Subdivisions** - Granular view by national subdivisions

### 3D Globe [#3d-globe]

Same four views as 2D, plus:

* Rotate by dragging
* Zoom in and out
* Traffic hotspots glow

The 3D view requires a Mapbox API token. Self-hosted installations need `MAPBOX_TOKEN` in environment variables. Cloud includes this automatically.

## Time Controls [#time-controls]

Pick date ranges to see how geographic distribution changes over time.

## Filtering [#filtering]

Apply the same filters as the main dashboard to see geographic distribution for specific segments.


# User Journeys (/de/docs/feature-guides/journeys)





<img alt="User Journeys Dashboard" src="__img0" />

User journeys show the actual paths people take as they move through your website, revealing how they flow from page to page.

## Reading the Visualization [#reading-the-visualization]

### Nodes [#nodes]

Each bar represents a page or event. Its height indicates how many users reached that point.

### Connections [#connections]

Lines between nodes show user flow. Thicker connections mean more users took that path.

### Flow Direction [#flow-direction]

The visualization flows left to right, showing progression through time.

## Key Patterns to Look For [#key-patterns-to-look-for]

* **Happy Path** - The most common route to conversion
* **Drop-off Points** - Where many users enter but few continue
* **Backtracking** - Users moving backward, often indicating confusion
* **Alternative Routes** - Unexpected paths to important pages

## Using Journey Insights [#using-journey-insights]

* **Simplify complex paths** - Create shortcuts to important pages
* **Fix drop-off points** - Investigate why users leave at certain pages
* **Amplify successful paths** - Make high-converting routes easier to follow
* **Reduce backtracking** - Improve navigation where users get lost

## Analysis Types [#analysis-types]

* **Entry point analysis** - Where do users go from a specific page?
* **Goal-based analysis** - How did converting users get there?
* **Full journey mapping** - Overall flow from entry to exit


# Main Dashboard (/de/docs/feature-guides/main-tab)





<img alt="Main Dashboard" src="__img0" />

The main dashboard is your home base in Rybbit Analytics, showing all key metrics at a glance.

## Top Metrics [#top-metrics]

* **Unique Users** - Different people who visited your site
* **Total Sessions** - Number of visits (30-minute inactivity starts a new session)
* **Total Pageviews** - Every page load from every visitor
* **Bounce Rate** - Percentage of single-page sessions
* **Pages Per Session** - Average pages viewed per visit
* **Session Duration** - Average time spent per visit

## Time Controls [#time-controls]

Select date ranges: Today, Yesterday, Last 7/30/60 days, This Week, This Month, All Time, or a custom range.

## Filters [#filters]

Combine filters for granular analysis:

* Device type, browser, OS
* Country, city
* Referrer, UTM parameters
* Custom event properties

A set of filters you use often can be saved as a [segment](/docs/segments) from the **Segments** tab of the Filter button, then applied to any report with one click.

## Main Chart [#main-chart]

Shows your selected metric over time. Click the metric selector to switch between Users, Sessions, Pageviews, Bounce Rate, Pages Per Session, or Session Duration.

## Traffic Sources [#traffic-sources]

See where your traffic comes from:

* **Direct** - Typed URL or bookmarks
* **Search** - Google, Bing, DuckDuckGo, etc.
* **Social** - Twitter, Facebook, LinkedIn, Reddit
* **Referral** - Other websites

Click any source to filter the entire dashboard to that traffic.

## UTM Parameters [#utm-parameters]

View campaign data: utm\_campaign, utm\_source, utm\_medium, utm\_term, utm\_content.

## Additional Breakdowns [#additional-breakdowns]

* **Top Pages** - Most visited URLs with pageviews, visitors, time on page, and bounce rate
* **Entry/Exit Pages** - Where visits begin and end
* **Devices & Browsers** - Desktop/mobile/tablet split, browser and OS breakdown
* **Screen Resolutions** - What sizes your visitors use
* **Geographic Data** - Countries and regions
* **Custom Events** - Click any event to filter to sessions containing it


# Pages (/de/docs/feature-guides/pages-tab)





<img alt="Pages Dashboard" src="__img0" />

The Pages tab shows detailed analytics for every URL on your site.

## Page Metrics [#page-metrics]

Each page displays:

* **Page URL** - The full path
* **Sessions** - Number of sessions that viewed this page
* **Average Time on Page** - How long visitors spend there

## Filtering [#filtering]

Use the same filters as the main dashboard to analyze specific segments:

* Mobile users from social media
* Desktop users who converted
* Users who triggered specific events

## Identifying Issues [#identifying-issues]

* Scan for pages with low time on page to find content that isn't engaging
* Look for pages with few sessions to find underperforming pages
* Compare entry pages to see which content attracts traffic


# Performance (/de/docs/feature-guides/performance)





<img alt="Performance Dashboard" src="__img0" />

The Performance tab tracks Core Web Vitals from real user data.

## Enabling Performance Tracking [#enabling-performance-tracking]

Enable Web Vitals in your [site settings](/docs/site-settings).

## Web Vitals [#web-vitals]

### Largest Contentful Paint (LCP) [#largest-contentful-paint-lcp]

How long the main content takes to load.

* **Good**: Under 2.5 seconds
* **Needs Improvement**: 2.5-4 seconds
* **Poor**: Over 4 seconds

### Cumulative Layout Shift (CLS) [#cumulative-layout-shift-cls]

How much content jumps around while loading.

* **Good**: Under 0.1
* **Needs Improvement**: 0.1-0.25
* **Poor**: Over 0.25

### Interaction to Next Paint (INP) [#interaction-to-next-paint-inp]

How quickly your site responds to user interactions.

* **Good**: Under 200ms
* **Needs Improvement**: 200-500ms
* **Poor**: Over 500ms

### First Contentful Paint (FCP) [#first-contentful-paint-fcp]

How long until the first content appears.

* **Good**: Under 1.8 seconds
* **Needs Improvement**: 1.8-3 seconds
* **Poor**: Over 3 seconds

### Time to First Byte (TTFB) [#time-to-first-byte-ttfb]

How long until the server responds.

* **Good**: Under 800ms
* **Needs Improvement**: 800-1800ms
* **Poor**: Over 1800ms

## Percentile Selector [#percentile-selector]

Choose which percentile to view (p50, p75, p90, p99). The p75 is commonly used for Core Web Vitals assessment.

## Comparison [#comparison]

Each metric shows the change from the previous period, with green indicating improvement and red indicating degradation.

## Breakdowns [#breakdowns]

* **By Page** - Find your slowest pages
* **By Device** - Compare mobile vs desktop performance
* **By Browser** - Identify browser-specific issues
* **By Country** - See geographic performance differences


# Retention (/de/docs/feature-guides/retention)





<img alt="Retention Dashboard" src="__img0" />

Retention analysis shows how many users come back to your site over time, revealing whether users find lasting value.

## Understanding Cohorts [#understanding-cohorts]

A cohort is a group of users who share a common start date. For example, all users who first visited on January 15th form one cohort.

## Reading the Retention Table [#reading-the-retention-table]

### Rows [#rows]

Each row is a different cohort, grouped by first visit date.

### Columns [#columns]

* **Day/Week 0** - Starting point (always 100%)
* **Day/Week 1, 2, 3...** - Users who returned after that period

### Numbers [#numbers]

Percentages show what portion of the original cohort returned. 40% in the "Day 7" column means 40% of users came back after a week.

### Color Coding [#color-coding]

* Lighter colors = higher retention
* Darker colors = more drop-off

## Key Insights [#key-insights]

* **Day 1 retention** - Did users find enough value to return the next day?
* **Day 7 retention** - Did users integrate your product into their routine?
* **Day 30 retention** - Have users formed a habit?

## Common Patterns [#common-patterns]

* **Cliff drop** - Sharp decline in first few days indicates onboarding issues
* **Steady decline** - Gradual drop suggests novelty wearing off
* **Plateau** - When retention levels off, you've found your core users

## Note on User ID Salting [#note-on-user-id-salting]

If [User ID Salting](/docs/site-settings) is enabled, retention beyond 24 hours becomes less accurate since user identifiers reset daily.


# Session Replay (/de/docs/feature-guides/session-replay)





<img alt="Session Replay" src="__img0" />

Session replay lets you watch anonymized recordings of real user sessions, showing mouse movements, clicks, scrolls, and page navigation.

## Enabling Session Replay [#enabling-session-replay]

Enable session replay in your [site settings](/docs/site-settings). The tracking script picks the setting up automatically — no script tag changes are needed. (Script-tag attributes like `data-replay-batch-size` and the `data-replay-mask-*` options only tune replay behavior; the on/off switch lives in site settings.)

## What You'll See [#what-youll-see]

* Mouse movements and clicks
* Scrolling behavior
* Page navigation
* Form interactions (with PII masked)
* User details: country, device, browser

## Using Session Replay [#using-session-replay]

* **UX optimization** - Identify where users get stuck or confused
* **Debug issues** - See exactly what happened when users report problems
* **Understand behavior** - Go beyond metrics to see the full user story
* **Share with your team** - Collaborate on findings

## Privacy [#privacy]

Session replay automatically masks sensitive information. Enable PII protection in your settings for additional masking of form inputs and text content.


# Sessions (/de/docs/feature-guides/sessions)



The Sessions tab shows individual user visits to your website, including all page views, interactions, and events during each session.

## Session Metrics [#session-metrics]

Each session displays:

* **Duration** - Time spent on site
* **Pages Visited** - Number of pages viewed
* **Events Triggered** - Custom events fired during the session
* **Device & Browser** - Technical environment
* **Location** - Geographic location based on IP
* **Entry/Exit Page** - Where the session started and ended
* **Bounce Status** - Whether the user left after one page

## Filtering Sessions [#filtering-sessions]

Filter by:

* Duration, pages visited, or events triggered
* Device type, browser, or location
* Referrer or traffic source
* Date range

## Session Replay [#session-replay]

If [session replay](/docs/product-analytics/replay-session) is enabled, you can watch a recording of any session to see exactly what the user did.


# Users (/de/docs/feature-guides/users)



The Users tab shows unique visitors and their behavior across multiple sessions.

## User Metrics [#user-metrics]

For each user, you'll see:

* **User ID** - Anonymized identifier
* **First/Last Visit** - When they first and most recently visited
* **Total Sessions** - Number of separate visits
* **Pages Viewed** - Total pages across all sessions
* **Events Triggered** - Total custom events
* **Device Type** - Desktop, mobile, or tablet
* **Location** - Geographic location

## Filtering Users [#filtering-users]

Filter by the standard dimension filters:

* Device type, browser, or operating system
* Country, region, or city
* Referrer, channel, or UTM parameters
* Pages visited (pathname, entry, or exit page)

Session count, pageviews, events, and first/last seen aren't filters, but you can sort the user list by those columns.

## Identified Users [#identified-users]

If you use the [identify API](/docs/identify-users), you can see your own user IDs alongside the anonymous identifiers.


# Claude Code (/de/docs/mcp/claude-code)



Connecting Claude Code to Rybbit lets it answer analytics questions mid-task — whether the error it just fixed still occurs in production, which pages get traffic before a refactor, whether a newly instrumented event is firing — and wire up goals and funnels as you ship features.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

The simplest way to connect — no API key to create or store:

```bash
claude mcp add --transport http rybbit https://app.rybbit.io/api/mcp
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Then run `/mcp` inside a Claude Code session, select **rybbit**, and choose **Authenticate**. Your browser opens to log in to Rybbit and approve access, and the connection acts with your user's role.

By default the server registers at the `local` scope — available to you in the current project only. Add `--scope user` to use it in all of your projects.

## Team setup [#team-setup]

OAuth makes the team setup trivial: commit a project-scoped `.mcp.json` at the repository root containing only the URL, and each developer authenticates once with `/mcp`. No secret ever touches the repo:

```json
{
  "mcpServers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp"
    }
  }
}
```

## Connect with an API key [#connect-with-an-api-key]

Use an [API key](/docs/mcp#1-create-an-api-key) instead when there is no browser to authenticate in (CI, headless `claude -p` runs) or when you want to hand the agent a narrower, scoped credential:

```bash
claude mcp add --transport http rybbit https://app.rybbit.io/api/mcp \
  --header "Authorization: Bearer <RYBBIT_API_KEY>"
```

In a committed `.mcp.json`, pass the key through an environment variable rather than hard-coding it — Claude Code expands `${VAR}` references from each developer's environment:

```json
{
  "mcpServers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${RYBBIT_API_KEY}"
      }
    }
  }
}
```

## Verify [#verify]

Run `claude mcp list` (or `/mcp` inside a session) to confirm the server shows as connected, then try:

> List my Rybbit sites and summarize last week's traffic for each.


# Claude Desktop (/de/docs/mcp/claude-desktop)





Adding Rybbit as a custom connector turns Claude into a conversational analytics interface: ask how a launch went, why traffic spiked on Tuesday, or where a funnel drops off — without opening the dashboard. Connectors are shared across claude.ai, Claude Desktop, and the mobile apps.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, the full tool list, permissions, and troubleshooting.

## Add the connector [#add-the-connector]

1. Open **Settings → Connectors** (in Claude Desktop: `Cmd/Ctrl + ,`, then **Connectors**; on claude.ai: your profile menu → **Settings** → **Connectors**).

2. Click **Add custom connector**.

3. Name it **Rybbit** and paste the endpoint URL:

   ```text
   https://app.rybbit.io/api/mcp
   ```

   For a self-hosted installation, use your configured `BASE_URL` host instead.

4. Confirm, then click **Connect**. Your browser opens Rybbit's [OAuth flow](/docs/mcp#or-connect-with-oauth) — log in and approve access. The connector acts with your user's role.

There is no API key to manage: custom connectors authenticate through OAuth, and the **Advanced settings** fields (OAuth client ID and secret) can stay empty — Rybbit registers the client automatically. Custom connectors are available on all Claude plans; the Free plan is limited to one.

<Callout type="warn">
  **Self-hosted installations must be publicly reachable.** Claude connects to
  custom connectors from Anthropic's infrastructure, not from your device — a
  Rybbit instance on a private network, behind a VPN, or on `localhost` will
  not connect, even if you can reach it in your own browser.
</Callout>

## Use it [#use-it]

Once connected, Rybbit appears in the chat's tools menu — enable it there if it isn't already. Then try:

> List my Rybbit sites and summarize last month's traffic for the main one.

Claude asks for confirmation before tool calls by default; destructive tools (deleting goals, funnels, sites) are marked so it always confirms those.


# Codex (/de/docs/mcp/codex)



Connecting Codex to Rybbit lets it check analytics as part of your development workflow — verifying that a fixed error stopped occurring, checking which routes get traffic before a refactor, or creating goals and funnels for features as you ship them.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

The simplest way to connect — add the server and log in:

```bash
codex mcp add rybbit --url https://app.rybbit.io/api/mcp
codex mcp login rybbit
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

`codex mcp login` opens your browser to log in to Rybbit and approve access; the connection acts with your user's role.

## Connect with an API key [#connect-with-an-api-key]

Use an [API key](/docs/mcp#1-create-an-api-key) instead for non-interactive runs or a narrower, scoped credential. Register the name of an environment variable holding the key:

```bash
codex mcp add rybbit --url https://app.rybbit.io/api/mcp \
  --bearer-token-env-var RYBBIT_API_KEY
```

Codex reads the key from that variable rather than storing it, so `RYBBIT_API_KEY` must be exported in the shell that launches Codex. Equivalently, configure it in `~/.codex/config.toml`:

```toml
[mcp_servers.rybbit]
url = "https://app.rybbit.io/api/mcp"
bearer_token_env_var = "RYBBIT_API_KEY"
```

## Verify [#verify]

Run `codex mcp list` (or `/mcp` inside the Codex TUI) to confirm the server is connected, then try:

> List my Rybbit sites and summarize last week's traffic for each.


# Cursor (/de/docs/mcp/cursor)



Connecting Cursor to Rybbit lets its agent check analytics while you code — confirming an error fix landed in production, checking traffic to a route before deleting it, or setting up goals and funnels for a new feature.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Add the server [#add-the-server]

1. [Create an API key](/docs/mcp#1-create-an-api-key) in Rybbit.
2. Add the server to `~/.cursor/mcp.json` (global — available in all projects) or `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "rybbit": {
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer <RYBBIT_API_KEY>"
      }
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Prefer the global file for a personal key. If you configure the server in a project's `.cursor/mcp.json`, don't commit the key — give each developer their own, ideally [scoped](/docs/mcp#1-create-an-api-key) to what the agent needs.

## Verify [#verify]

Open **Cursor Settings → MCP**: the server should show as connected with its tool list, and can be toggled on and off there. Then ask the agent:

> List my Rybbit sites and summarize last week's traffic for each.


# MCP (/de/docs/mcp)





Rybbit includes a hosted [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) endpoint. It gives an AI assistant read and write access to your analytics: exploring traffic and behavior data, and managing sites, goals, funnels, organization members, teams, and user profiles — through the same API the dashboard uses, with the same access checks, roles, and rate limits.

Your MCP client connects to Rybbit over HTTPS and sends your API key with each protocol request. Rybbit verifies the key before processing any message, and every tool call is authorized against the key user's role and site access.

## Connect a client [#connect-a-client]

If your client supports the MCP authorization flow — Claude Code, Codex, Claude Desktop, and opencode all do — you can [connect with OAuth](#or-connect-with-oauth) and skip API keys entirely. The steps below describe the API-key path, which works in every client and supports scoped credentials.

### 1. Create an API key [#1-create-an-api-key]

1. Open **Settings → Account** in Rybbit.
2. Create a key in the **Personal API Keys** section.
3. Copy it immediately. Rybbit only shows a new key once.

A key created without permissions can do everything its user can do. To hand an agent a narrower credential, create the key with scoped permissions (`POST /api/user/api-keys` with a `permissions` object, e.g. `{"analytics": ["read"], "goals": ["read", "write"]}`): the MCP tool list and every API call are then limited to those `resource:action` scopes. `write` implies `read` on the same resource, and scopes never elevate — org admin/owner requirements still apply. Deleting the key revokes the connection.

### 2. Add the endpoint [#2-add-the-endpoint]

Use this Streamable HTTP URL for Rybbit Cloud:

```text
https://app.rybbit.io/api/mcp
```

For a self-hosted installation, replace the host with your configured `BASE_URL`:

```text
https://analytics.example.com/api/mcp
```

Configure your client to send this header on every request:

```text
Authorization: Bearer <RYBBIT_API_KEY>
```

MCP clients use different configuration formats. A typical remote-server configuration has this shape:

```json
{
  "mcpServers": {
    "rybbit": {
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer <RYBBIT_API_KEY>"
      }
    }
  }
}
```

Use your client's secret or environment-variable support when available instead of saving the key in a file. Query-string API keys are not accepted by the MCP endpoint. Per-client walkthroughs — Claude Code, Codex, Claude Desktop, Cursor, VS Code, opencode — are in [Client guides](#client-guides) below.

### Or connect with OAuth [#or-connect-with-oauth]

Clients that support the MCP authorization flow can skip API keys entirely: add the endpoint URL with no headers, and the client discovers Rybbit's authorization server through the standard well-known metadata (`/.well-known/oauth-protected-resource`), registers itself, and opens a browser window for you to log in and approve access. The resulting access token acts with your user's role, exactly like an API key would.

OAuth grants support the same `resource:action` scopes as API keys (advertised in `scopes_supported`). A grant that requests only the standard OIDC scopes is unrestricted; a grant that requests custom scopes like `analytics:read` is limited to them. The requesting client controls which scopes it asks for — consent is currently approve-or-deny as a whole.

### 3. Start with context [#3-start-with-context]

Ask the assistant to call `list_sites`, or prompt it with something like:

> List my Rybbit sites, summarize last month's traffic for the docs site, and create a goal for signups.

`list_sites` returns the numeric `site_id` and `organization_id` required by the other tools, plus the key's role in each organization. It does not return API keys or member email addresses.

## Client guides [#client-guides]

Coding agents can use the endpoint to pull analytics into your development workflow — checking whether an error you just fixed still occurs in production, or looking up which pages matter before a refactor — and chat clients like Claude Desktop turn it into a conversational analytics interface. Follow the guide for your client:

<Cards>
  <Card icon="<SiClaude />" title="Claude Code" description="One command with OAuth or an API key, plus a no-secrets team setup" href="/docs/mcp/claude-code" />

  <Card title="Codex" description="codex mcp add, then OAuth login or a key from the environment" href="/docs/mcp/codex" />

  <Card icon="<SiClaude />" title="Claude Desktop" description="Add a custom connector on claude.ai, desktop, and mobile" href="/docs/mcp/claude-desktop" />

  <Card title="Cursor" description="mcp.json with an API key header" href="/docs/mcp/cursor" />

  <Card title="VS Code" description="Copilot agent mode, with the key kept out of the config file" href="/docs/mcp/vscode" />

  <Card title="opencode" description="Remote server config with OAuth login or env-based headers" href="/docs/mcp/opencode" />
</Cards>

Any other MCP client that supports Streamable HTTP works with the generic configuration from [step 2](#2-add-the-endpoint).

## Available tools [#available-tools]

### Analytics (read) [#analytics-read]

| Tool                      | Returns                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `get_overview`            | Sessions, pageviews, users, pages per session, bounce rate, and session duration       |
| `get_overview_timeseries` | The overview KPIs bucketed over time                                                   |
| `get_breakdown`           | Sessions broken down by one dimension (pages, referrers, countries, devices, UTM, ...) |
| `get_live_stats`          | Visitors active on the site right now                                                  |
| `get_event_names`         | Custom event names tracked on the site with counts                                     |
| `get_errors`              | JavaScript errors grouped by name/message with occurrence counts                       |
| `get_web_vitals`          | Core Web Vitals percentiles (LCP, CLS, INP, FCP, TTFB)                                 |
| `get_retention`           | User retention cohort table                                                            |
| `get_journeys`            | Most common page-to-page navigation paths                                              |
| `get_annotations`         | Notes pinned to dates on the traffic chart (launches, deploys, campaigns, outages)     |
| `list_segments`           | Saved segments: named, reusable filter sets for a site or the whole organization       |
| `apply_segment`           | Overview KPIs for visitors matching a saved segment, with its filters for reuse        |

### Sites [#sites]

| Tool                 | Does                                                                                   |
| -------------------- | -------------------------------------------------------------------------------------- |
| `list_sites`         | List organizations and sites the key can access (call this first)                      |
| `get_site`           | One site's full configuration                                                          |
| `create_site`        | Add a new site to an organization &#x2A;(admin)*                                       |
| `update_site_config` | Change site settings: name, domain, tracking features, exclusions, tags &#x2A;(admin)* |
| `delete_site`        | Permanently delete a site and its data &#x2A;(admin, destructive)*                     |

### Goals & funnels [#goals--funnels]

| Tool             | Does                                                   |
| ---------------- | ------------------------------------------------------ |
| `get_goals`      | Conversion goals with conversion stats                 |
| `create_goal`    | Create a path, event, or autocapture goal              |
| `update_goal`    | Replace a goal's definition                            |
| `delete_goal`    | Permanently delete a goal &#x2A;(destructive)*         |
| `get_funnels`    | Saved funnel definitions                               |
| `analyze_funnel` | Compute an ad-hoc funnel without saving it             |
| `save_funnel`    | Save a funnel, or update one by passing `funnel_id`    |
| `delete_funnel`  | Permanently delete a saved funnel &#x2A;(destructive)* |

### People [#people]

| Tool                 | Does                                                                        |
| -------------------- | --------------------------------------------------------------------------- |
| `get_users`          | Person inventory with per-user aggregates and traits (sortable, searchable) |
| `get_user`           | One person's profile: traits, linked devices, vitals, locations             |
| `identify_user`      | Link an anonymous device to your user ID and merge traits                   |
| `update_user_traits` | Replace a person's traits wholesale                                         |
| `delete_user`        | GDPR erasure of one person's analytics data &#x2A;(admin, destructive)*     |

### Organization & teams [#organization--teams]

| Tool                        | Does                                                           |
| --------------------------- | -------------------------------------------------------------- |
| `list_members`              | Organization members with roles, site access, and teams        |
| `add_member`                | Add an existing Rybbit user to the organization &#x2A;(admin)* |
| `update_member_site_access` | Restrict a member to specific sites &#x2A;(admin)*             |
| `list_teams`                | Teams with members and site access                             |
| `create_team`               | Create a team &#x2A;(admin)*                                   |
| `update_team`               | Rename a team or replace its members/sites &#x2A;(admin)*      |
| `delete_team`               | Permanently delete a team &#x2A;(admin, destructive)*          |

### Raw data & SQL [#raw-data--sql]

| Tool               | Does                                                                   |
| ------------------ | ---------------------------------------------------------------------- |
| `get_sessions`     | Recent visitor sessions with full attribution                          |
| `get_session`      | One session's detail plus its event timeline                           |
| `get_events`       | Raw recent events, newest first                                        |
| `get_query_schema` | The ClickHouse schema and rules for `run_query`                        |
| `run_query`        | Read-only ClickHouse SQL against the site-scoped `scoped_events` table |

Analytics tools accept optional time inputs (`start_date`/`end_date` with an IANA `time_zone`, or `past_minutes`) and the same filters as the dashboard. Omitting time inputs queries all time; an unrecognized `time_zone` is rejected before the call is made. `get_sessions`, `get_events`, and `get_users` accept an optional `fields` list to return only the named row columns, which keeps large result sets small.

## Permissions and roles [#permissions-and-roles]

The MCP surface mirrors the REST API's permission model:

* **Read tools** work for any member with access to the site.
* **Write tools** need at least member-level site access (goals, funnels, `identify_user`, `update_user_traits`, `save_funnel`).
* **Tools marked &#x2A;(admin)*** require the API key's user to hold the **admin or owner** role in the organization; `add_member` can grant the `owner` role only from an owner's key. The REST layer enforces all of this — an underprivileged key gets a 403 with an explanatory message.

To give an assistant a read-only or read-mostly view, create a **scoped** API key (see step 1): grant only the `resource:action` scopes it needs — e.g. `{"analytics": ["read"], "sessions": ["read"]}` for a reporting agent. The MCP tool list is filtered to those scopes, and any out-of-scope call returns `403 { "error": "Insufficient scope", "required": "goals:write" }`. Alternatively, connecting with a member-role user's key hides nothing but refuses every call requiring the admin/owner role.

OAuth clients request scopes through the standard grant. Rybbit advertises the same `resource:action` scopes in its discovery metadata; a grant carrying no custom scopes (or only the standard OIDC scopes) is treated as full access, for backward compatibility.

## Destructive tools [#destructive-tools]

`delete_goal`, `delete_funnel`, `delete_site`, `delete_team`, and `delete_user` permanently destroy data and are marked with the MCP `destructiveHint` annotation, so well-behaved clients ask for confirmation before invoking them. `delete_site` and `delete_user` (the GDPR-erasure path) also remove recorded events and replays, with erasure completing asynchronously.

## Data and security boundary [#data-and-security-boundary]

* The API key is verified before any MCP message is processed, and each tool call re-runs the corresponding REST route's own access checks, role requirements, and rate limits.
* The surface returns whatever the REST API returns for your role — including session-level records and, where a site has IP tracking enabled, visitor IP addresses. Connect only AI clients you trust with that data, and use a separate, revocable API key per integration.
* Text originating in tracked traffic (page titles, paths, referrers, event names, traits) is stripped of control and bidi-override characters. AI clients should still treat these values as untrusted data, never as instructions.
* `run_query` is restricted to a read-only, site-scoped table with row and execution-time caps.
* The server does not contain an AI model or send analytics to an AI provider. Data only leaves Rybbit in response to the MCP client you configure.
* The endpoint is stateless. Each HTTP request is independently authenticated.

## Troubleshooting [#troubleshooting]

* **401 Unauthorized:** The client did not send a Bearer credential, or the key/token is invalid, expired, or revoked. OAuth-capable clients re-authenticate automatically via the `WWW-Authenticate` challenge.
* **OAuth login loop or "table does not exist" (self-hosted):** Run `npm run db:push` in `server/` to create the OAuth tables, then retry.
* **403 in tool results:** The key's user lacks access to that site or organization — or the tool requires an org admin/owner role. Check the `role` field in `list_sites`.
* **403 "Insufficient scope":** The credential was created without the `resource:action` scope this tool needs (the `required` field names it). Use a key or OAuth grant that includes it.
* **429 Too Many Requests:** The API key exceeded its plan's rate limit.
* **503 Service Unavailable:** Rybbit could not verify the key. Retry the request; do not replace a known-valid key based on this response.
* **405 Method Not Allowed on GET:** This is expected. The stateless endpoint accepts MCP messages over `POST`.
* **Site access error:** Call `list_sites` again. Membership or site permissions may have changed.


# opencode (/de/docs/mcp/opencode)



Connecting opencode to Rybbit lets it pull analytics into your terminal workflow — verifying an error fix in production, checking a route's traffic before removing it, or wiring up goals and funnels as you ship.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

Add the server to `opencode.json` at your project root (or your global opencode config):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rybbit": {
      "type": "remote",
      "url": "https://app.rybbit.io/api/mcp",
      "enabled": true
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Then authenticate:

```bash
opencode mcp auth rybbit
```

Your browser opens Rybbit's [OAuth flow](/docs/mcp#or-connect-with-oauth) — log in and approve access. The connection acts with your user's role, and the committed config carries no secret. `opencode mcp logout rybbit` removes the stored credential.

## Connect with an API key [#connect-with-an-api-key]

To use an [API key](/docs/mcp#1-create-an-api-key) instead — for non-interactive runs or a narrower, scoped credential — add a headers block that reads the key from the environment, so the config stays committable:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rybbit": {
      "type": "remote",
      "url": "https://app.rybbit.io/api/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:RYBBIT_API_KEY}"
      }
    }
  }
}
```

## Verify [#verify]

Run `opencode mcp list` to see the server and its authentication status (`opencode mcp debug rybbit` gives detailed diagnostics), then try:

> List my Rybbit sites and summarize last week's traffic for each.


# VS Code (/de/docs/mcp/vscode)



Connecting VS Code to Rybbit gives Copilot's agent mode access to your analytics — checking whether a fixed error still occurs, looking up which pages matter before a refactor, or creating goals for a feature as you build it.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Add the server [#add-the-server]

1. [Create an API key](/docs/mcp#1-create-an-api-key) in Rybbit.
2. Create `.vscode/mcp.json` in your workspace. The `inputs` block keeps the key out of the file — VS Code prompts for it once when the server first starts and stores it securely, so this file is safe to commit:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "rybbit-api-key",
      "description": "Rybbit API key",
      "password": true
    }
  ],
  "servers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:rybbit-api-key}"
      }
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

To make the server available in every workspace instead, run **MCP: Open User Configuration** from the Command Palette and add the same JSON there. **MCP: Add Server** offers a guided setup as an alternative to editing the file.

## Verify [#verify]

Run **MCP: List Servers** from the Command Palette — Rybbit should be listed with its tools, which also appear in the tools picker in Copilot's agent mode. Then ask the agent:

> List my Rybbit sites and summarize last week's traffic for each.


# Angular (/de/docs/guides/angular)





An Angular CLI project serves one HTML shell, `src/index.html`, for every route. Paste the snippet into its `<head>` and the script loads once for the whole app.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Angular [#add-the-snippet-to-angular]

    Open `src/index.html` and paste the snippet just before `</head>`:

    ```html title="src/index.html"
    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>MyAngularApp</title>
      <base href="/">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
      <app-root></app-root>
    </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Navigation through the Angular Router is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Declare `rybbit` on `window` once so TypeScript accepts the call, then call `window.rybbit.event()` from any component or service. Guard the call so a blocked script does not throw.

```typescript title="src/app/feature/feature.component.ts"
import { Component } from "@angular/core";

declare global {
  interface Window {
    rybbit?: {
      event: (eventName: string, eventData?: Record<string, any>) => void;
      pageview: () => void;
    };
  }
}

@Component({
  selector: "app-feature",
  template: `<button (click)="onFeatureClick()">Use Feature</button>`,
})
export class FeatureComponent {
  onFeatureClick(): void {
    if (window.rybbit) {
      window.rybbit.event("feature_used", { featureName: "Amazing Feature" });
    }
  }
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: this is rare. If it happens, subscribe to `Router.events`, filter for `NavigationEnd` and call `window.rybbit.pageview()`; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ASP.NET Core (/de/docs/guides/aspnet)





ASP.NET Core MVC and Razor Pages apps share one layout file, `_Layout.cshtml`, that wraps every view, so the snippet goes into its `<head>`. Keep the site ID in `appsettings.json` and inject `IConfiguration` into the layout so nothing is hard-coded.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ASP.NET Core [#add-the-snippet-to-aspnet-core]

    #### Configure the site ID [#configure-the-site-id]

    Add a `Rybbit` section to `appsettings.json`:

    ```json filename="appsettings.json"
    {
      "Rybbit": {
        "InstanceUrl": "https://app.rybbit.io",
        "SiteId": "YOUR_SITE_ID"
      }
    }
    ```

    To keep the ID out of source control or vary it per environment, leave `SiteId` empty in `appsettings.json` and set it in `appsettings.Production.json`, or as the environment variable `Rybbit__SiteId` (double underscore separates configuration sections).

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open the layout file:

    * Controllers with views: `Views/Shared/_Layout.cshtml`
    * Razor Pages: `Pages/Shared/_Layout.cshtml`

    Inject `IConfiguration` at the top and add the tag inside `<head>`:

    ```razor filename="Views/Shared/_Layout.cshtml"
    @inject IConfiguration Configuration
    @{
        var rybbitSiteId = Configuration["Rybbit:SiteId"];
        var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
    }
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>@ViewData["Title"] - MyApp</title>
        <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />

        @if (!string.IsNullOrEmpty(rybbitSiteId))
        {
            <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
        }
    </head>
    ```

    If `Microsoft.Extensions.Configuration` is not already imported in `_ViewImports.cshtml`, add `@using Microsoft.Extensions.Configuration` above the `@inject` line.

    The `@if` guard skips the tag when `SiteId` is empty, so development is not tracked unless you set the value there. If your app has more than one layout, add the tag to each, or move it into a partial view and render it with `<partial name="_Rybbit" />` from every layout.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: environment-specific files such as `appsettings.Development.json` override `appsettings.json`, so check which environment you are running (`ASPNETCORE_ENVIRONMENT`) and that the `Rybbit` section exists there or in the base file. Environment variables override both.
* **Content Security Policy**: if middleware adds a `Content-Security-Policy` header, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Response caching or output caching**: the tag is rendered server-side, so a cached response keeps whatever configuration was active when it was cached. Clear the cache after changing the site ID.
* **Self-hosted instance**: set `Rybbit:InstanceUrl` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Astro (/de/docs/guides/astro)





Astro pages share a layout component that renders the `<html>` document. Add the snippet to the `<head>` of that layout and every page that uses it is tracked.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Astro [#add-the-snippet-to-astro]

    Open your shared layout, usually `src/layouts/Layout.astro`, and paste the snippet inside `<head>`. Add `is:inline` so Astro leaves the tag as-is instead of bundling it:

    ```astro title="src/layouts/Layout.astro"
    ---
    const { title } = Astro.props;
    ---
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title>{title}</title>
        <script is:inline src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <slot />
      </body>
    </html>
    ```

    If you do not use a shared layout, add the same tag to the `<head>` of each page in `src/pages/`. A layout is easier to maintain.

    Astro builds a multi-page site by default, so each navigation is a full page load and a new pageview. With [view transitions](https://docs.astro.build/en/guides/view-transitions/) enabled, client-side navigation is tracked automatically when the URL changes.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a client-side `<script>` in any `.astro` component, or from inside a framework island the same way you would in that framework.

```astro title="src/components/TrackedButton.astro"
<button id="tracked-button">Click me</button>

<script>
  document.getElementById("tracked-button")?.addEventListener("click", () => {
    if (window.rybbit) {
      window.rybbit.event("astro_button_click", { source: "TrackedButton.astro" });
    }
  });
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing with view transitions**: this is rare. If it happens, listen for Astro's `astro:after-swap` event in a client-side script and call `window.rybbit.pageview()`; test the default behaviour first.
* **Proxying through your own domain**: Astro can serve the script from your domain with SSR middleware. See the [Astro proxy guide](/docs/proxy-guide/astro).

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# BigCommerce (/de/docs/guides/bigcommerce)





BigCommerce's **Script Manager** adds scripts to every storefront page without theme edits, and it is also where the order-confirmation purchase event goes. Editing the theme's `head.html` works too.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to BigCommerce [#add-the-snippet-to-bigcommerce]

    <Tabs items="[&#x22;Script Manager&#x22;, &#x22;Theme files&#x22;]">
      <Tab>
        1. In the control panel, go to **Storefront > Script Manager** and click **Create a Script**.
        2. Fill in the settings:
           * **Name**: Rybbit Analytics
           * **Placement**: Head
           * **Location**: All pages
           * **Script category**: Analytics
           * **Script type**: Script
        3. Paste the snippet into **Script contents** and click **Save**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Back up your theme before editing files.
        </Callout>

        1. Go to **Storefront > Themes**, click **Advanced** on your current theme, then **Edit Theme Files**.
        2. Open **templates > components > common** and then `head.html`.
        3. Paste the snippet at the end of the file, before the closing `</head>` tag, and click **Save**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Create a second script in Script Manager with **Placement: Footer**, **Location: Order Confirmation** and **Script type: Script**. BigCommerce runs Script Manager contents through Handlebars, so expressions such as `checkout.order.id` are filled in with the order data before the page is served:

```html
<script>
(function () {
  function waitForRybbit(callback, timeout) {
    var start = Date.now();
    (function check() {
      if (window.rybbit && typeof window.rybbit.event === 'function') {
        callback();
      } else if (Date.now() - start < timeout) {
        setTimeout(check, 100);
      }
    })();
  }

  waitForRybbit(function () {
    {{#if checkout.order}}
    window.rybbit.event('purchase', {
      transaction_id: '{{checkout.order.id}}',
      value: {{checkout.subtotal.value}},
      currency: '{{checkout.currency.code}}'
    });
    {{/if}}
  }, 5000);
})();
</script>
```

`waitForRybbit` polls until the tracking script from the head has defined `window.rybbit`, so the event is not lost if the confirmation page runs the footer script first.

## Troubleshooting [#troubleshooting]

* **Script not on the page**: confirm the script is enabled in Script Manager, then purge the store cache under **Server Settings > Store-level caching > Purge cache**.
* **Purchase event missing**: the purchase script must use the **Order Confirmation** location, and the `checkout.order`, `checkout.subtotal` and `checkout.currency` Handlebars objects depend on your BigCommerce checkout version. Place a test order to confirm the event arrives.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Blazor (/de/docs/guides/blazor)





Where the snippet goes depends on the Blazor hosting model: a Blazor Web App keeps its `<head>` in `Components/App.razor`, a standalone Blazor WebAssembly app in `wwwroot/index.html`, and a Blazor Server app (.NET 7 and earlier) in `Pages/_Host.cshtml`. In each case the tag is added once and stays on the page while Blazor handles navigation client-side.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Blazor [#add-the-snippet-to-blazor]

    <Tabs items="[&#x22;Blazor Web App&#x22;, &#x22;Blazor WebAssembly (standalone)&#x22;, &#x22;Blazor Server (.NET 7 and earlier)&#x22;]">
      <Tab>
        `App.razor` is rendered on the server, so it can read the site ID from `appsettings.json`. Add a `Rybbit` section:

        ```json filename="appsettings.json"
        {
          "Rybbit": {
            "InstanceUrl": "https://app.rybbit.io",
            "SiteId": "YOUR_SITE_ID"
          }
        }
        ```

        Then inject `IConfiguration` in `Components/App.razor` and add the tag inside `<head>`:

        ```razor filename="Components/App.razor"
        @inject IConfiguration Configuration
        @{
            var rybbitSiteId = Configuration["Rybbit:SiteId"];
            var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
        }
        <!DOCTYPE html>
        <html lang="en">

        <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <base href="/" />
            <link rel="stylesheet" href="@Assets["app.css"]" />
            <HeadOutlet />

            @if (!string.IsNullOrEmpty(rybbitSiteId))
            {
                <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
            }
        </head>
        ```

        Override the value per environment with `appsettings.Production.json` or the environment variable `Rybbit__SiteId`.
      </Tab>

      <Tab>
        A standalone WebAssembly app ships `wwwroot/index.html` as a static file, so add the tag directly inside `<head>`:

        ```html filename="wwwroot/index.html"
        <head>
            <base href="/" />
            <link rel="stylesheet" href="css/app.css" />

            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        The site ID is public on every platform (it is in the page source), so a static value here is fine; `wwwroot/appsettings.json` is equally visible to the browser and offers no advantage for this value.
      </Tab>

      <Tab>
        Add the `Rybbit` section to `appsettings.json` as in the Blazor Web App tab, then open `Pages/_Host.cshtml` (or `Pages/_Layout.cshtml` in .NET 6 projects, where the `<head>` lives) and add the tag:

        ```razor filename="Pages/_Host.cshtml"
        @page "/"
        @using Microsoft.Extensions.Configuration
        @inject IConfiguration Configuration
        @{
            var rybbitSiteId = Configuration["Rybbit:SiteId"];
            var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
        }
        <!DOCTYPE html>
        <html lang="en">
        <head>
            <base href="~/" />
            <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

            @if (!string.IsNullOrEmpty(rybbitSiteId))
            {
                <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
            }
        </head>
        ```
      </Tab>
    </Tabs>

    #### Navigation [#navigation]

    Blazor's router, `NavigationManager.NavigateTo` and enhanced navigation in Blazor Web Apps all update the URL through `history.pushState` (or `replaceState` when `replace: true`) rather than reloading the page. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). Enhanced navigation patches the DOM without re-running scripts already in `<head>`, which is what you want: the tracker loads once and keeps running. `NavigateTo(url, forceLoad: true)` and links with `data-enhance-nav="false"` do a full page load, which the script tracks as a new pageview.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in a Blazor Web App**: `App.razor` reads server-side configuration, so check the `appsettings` file for the active `ASPNETCORE_ENVIRONMENT`; environment variables override the files.
* **Blazor WebAssembly PWA**: `index.html` is cached by the service worker. Users receive the new tag only after the app is republished and the service worker updates.
* **Content Security Policy**: if you set one, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `Rybbit:InstanceUrl` (or the static URL in `index.html`) to your own domain without a trailing slash.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Bolt (/de/docs/guides/bolt)





Bolt has no settings field for custom head code (its **Analytics** project setting only shows traffic for published sites), so the snippet goes into the app's HTML head as a code change: prompt Bolt to add it, or switch to Code view and paste it into the root HTML or layout file. Publish the project again afterwards.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Bolt [#add-the-snippet-to-bolt]

    <Tabs items="[&#x22;Ask Bolt&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of every page and keep all existing head tags:
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Review the change Bolt makes before you move on: the tag should be in the document head, not inside a component.
      </Tab>

      <Tab>
        Click the **Code Preview** icon (`<>`) at the top center to switch to Code view, then open the file that owns the `<head>` for the framework Bolt chose:

        * **Vite** projects (React, Vue, Svelte): `index.html` at the project root.
        * **Next.js** projects: `app/layout.tsx`, using the `next/script` component as in the [Next.js guide](/docs/guides/react/next-js).
        * Any other framework: ask Bolt "which file renders the HTML head?" and edit that one.

        For a Vite project, paste the snippet before `</head>`:

        ```html title="index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Click **Save** or press **Ctrl+S**.
      </Tab>
    </Tabs>

    Publish the change: open the **Publish** menu and click **Publish** the first time, or **Update** for a site that is already live. In-app navigation is tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Published site unchanged**: edits are not applied to the live site until you click **Update** in the **Publish** menu.
* **Bolt removed the tag**: later prompts can regenerate `index.html` or the layout. Right-click the file in the **Files** list and choose **Lock file** so Bolt leaves it alone, or add a line to the project's **Knowledge** telling it to keep the Rybbit script.
* **Expo (mobile) projects**: a script tag only runs in the web build. For the native app, use the [JavaScript SDK](/docs/sdks/web) instead.
* **Numbers differ from Bolt's Analytics**: Bolt's built-in counts include crawlers and bots; Rybbit filters them.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Bubble.io (/de/docs/guides/bubble)





Bubble adds custom header code to every page of your app through the **SEO / metatags** settings tab, so the snippet goes there once and ships with your next deploy.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Bubble.io [#add-the-snippet-to-bubbleio]

    1. Open your app in the Bubble editor and click the **Settings** tab in the left sidebar.
    2. Open the **SEO / metatags** sub-tab.
    3. Scroll to **Script/meta tags in header** and paste the snippet. It is added to the `<head>` of every page in the app.
    4. Deploy the app to **Live**. The development version does not pick up the change until you deploy.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Bubble workflows can run arbitrary JavaScript through a **Run JavaScript** action (provided by the free Toolbox plugin). Use it to send events from any workflow trigger.

1. Open the **Workflow** tab and pick the trigger, for example *When Button Signup is clicked*.
2. Add a **Run JavaScript** action.
3. Paste the call, using Bubble's dynamic expressions for the values:

```javascript
if (window.rybbit) {
  window.rybbit.event("signup_clicked", {
    plan: "Current User's Plan",
  });
}
```

## Troubleshooting [#troubleshooting]

* **Only the first pageview is tracked**: Bubble apps that switch between groups on a single page do not change the URL, so there is nothing for the script to detect. Add a **Run JavaScript** action that calls `window.rybbit.pageview()` when the group becomes visible, or track those views as custom events. Apps that navigate between real Bubble pages are tracked automatically.
* **Snippet missing on the live site**: the header script is versioned with your app, so check that you deployed to Live after saving the setting.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Capacitor (/de/docs/guides/capacitor)





Capacitor wraps a normal web app in a native WebView, so the snippet goes in the `<head>` of that web app's `index.html` and ships to iOS and Android with `npx cap sync`. If the app is built with Ionic Angular, React or Vue, follow the [Angular](/docs/guides/angular), [React](/docs/guides/react/vite-cra) or [Vue](/docs/guides/vue/vite) guide for where the tag lives, then come back here for the WebView origin settings.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Capacitor [#add-the-snippet-to-capacitor]

    1. Paste the snippet into the `<head>` of your web app's `index.html` (the file in the `webDir` folder from `capacitor.config`, after your framework's build):

    ```html title="index.html"
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    2. Enable `CapacitorHttp`, which routes `window.fetch` through native HTTP. The iOS WebView runs on `capacitor://localhost`, and Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so without this the browser blocks the requests on iOS:

    ```ts title="capacitor.config.ts"
    import type { CapacitorConfig } from "@capacitor/cli";

    const config: CapacitorConfig = {
      appId: "com.example.app",
      appName: "My App",
      webDir: "dist",
      plugins: {
        CapacitorHttp: {
          enabled: true,
        },
      },
    };

    export default config;
    ```

    3. Build the web app, then copy it into the native projects:

    ```bash
    npm run build
    npx cap sync
    ```

    Android serves the app from `https://localhost` (`server.androidScheme` defaults to `https`), which is a regular origin, so tracking works there with or without `CapacitorHttp`. In-app route changes are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.

    <Callout type="info">
      Use the script tag rather than the `@rybbit/js` npm package on Capacitor. The package sends events with `navigator.sendBeacon`, which `CapacitorHttp` does not patch, so its requests from `capacitor://localhost` are still blocked on iOS.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Works on Android and in the browser, silent on iOS**: `CapacitorHttp` is not enabled, or the native projects were not re-synced after changing the config. Run `npx cap sync` and rebuild in Xcode.
* **Changes do not appear on device**: `npx cap sync` copies the built web bundle; edit the source, rebuild the web app, then sync again.
* **Live reload during development**: with `server.url` pointing at your dev server the WebView loads an `http://` origin, so requests succeed even without `CapacitorHttp`. Do not read a working dev build as proof that the production build is configured.
* **Every pageview shows `localhost` as hostname**: expected. `server.hostname` defaults to `localhost` on both platforms; filter by site, not hostname.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Carrd (/de/docs/guides/carrd)





Carrd builds one-page sites, and the snippet goes into the **Head** embed code field in the site settings.

<Callout type="warn">
  Custom head code requires a **Carrd Pro** subscription (Pro Standard or Pro Plus). The Embed Code feature is not included on Pro Lite.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Carrd [#add-the-snippet-to-carrd]

    1. Open your site in the Carrd editor and click the **Settings** gear in the top right.
    2. Open the **Settings** tab and scroll to **Embed Code**.
    3. Paste the following into the **Head** field:

    ```html
    <script>
      (function () {
        var s = document.createElement("script");
        s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
        s.defer = true;
        document.head.appendChild(s);
      })();
    </script>
    ```

    This wraps the snippet in a small loader so Carrd's embed processing cannot rewrite the tag.

    4. Click **Save**, then **Publish**. Changes are not live until you publish.

    If your site has multiple pages (a Pro Plus feature), the head code loads on all of them.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **The Head field is missing**: the site is on Pro Lite or the free plan. Upgrade to Pro Standard or Pro Plus.
* **Snippet not in the page source**: the site was saved but not published. Publish again from the editor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Chrome extension (/de/docs/guides/chrome-extension)





Manifest V3 requires every piece of executable code to ship inside the extension package, and the `extension_pages` Content Security Policy is fixed at `script-src 'self' 'wasm-unsafe-eval'; object-src 'self'` with no way to relax it. A remote `<script>` tag can therefore never load in an extension page. Bundle the `@rybbit/js` SDK into your popup, options or side panel page instead, and grant `host_permissions` for the analytics host.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.

    You only need the site ID from the snippet; the script tag itself is not used in an extension.
  </Step>

  <Step>
    ### Add the snippet to Chrome extension [#add-the-snippet-to-chrome-extension]

    1. Install the SDK in the extension project:

    ```bash
    npm install @rybbit/js
    ```

    2. Initialise it in the entry script of each extension page you want to track (the popup from `action.default_popup`, the options page from `options_ui.page`, the side panel from `side_panel.default_path`). The SDK needs `window` and `document`, so do not import it in the service worker.

    ```js title="src/popup.js"
    import rybbit from "@rybbit/js";

    await rybbit.init({
      analyticsHost: "https://app.rybbit.io/api",
      siteId: "YOUR_SITE_ID",
    });

    // Extension pages have URLs like chrome-extension://<id>/popup.html.
    // Report a readable path instead:
    rybbit.pageview("/popup");
    ```

    3. Grant the extension permission to call the analytics host. Requests from extension pages to origins listed in `host_permissions` are not subject to CORS:

    ```json title="manifest.json"
    {
      "manifest_version": 3,
      "host_permissions": ["https://app.rybbit.io/*"]
    }
    ```

    4. Build the extension with your bundler (Vite, webpack, Rollup) so `@rybbit/js` ends up inside the package, then reload the unpacked extension at `chrome://extensions`.

    The default extension CSP does not restrict `connect-src`, so no `content_security_policy` entry is required. If you define your own policy, add `https://app.rybbit.io` to its `connect-src`.

    <Callout type="warn">
      Do not initialise the SDK in a content script. Content scripts run inside third-party websites; tracking there records other people's pages under your site ID, and content scripts are subject to the host page's same-origin policy in any case.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `rybbit.event()` from the page script, or use data attributes on buttons in your popup HTML:

```js title="src/popup.js"
document.getElementById("save")?.addEventListener("click", () => {
  rybbit.event("settings_saved", { theme: "dark" });
});
```

```html title="popup.html"
<button data-rybbit-event="upgrade_click" data-rybbit-prop-plan="pro">Upgrade</button>
```

## Troubleshooting [#troubleshooting]

* **`Refused to load the script` in the popup console**: the fixed `extension_pages` CSP blocked a remote tag. Remove it and use the SDK.
* **`POST /api/track` blocked by CORS**: `host_permissions` is missing or does not match. The pattern must include the path wildcard: `https://app.rybbit.io/*`.
* **Self-hosted Rybbit**: replace `https://app.rybbit.io` in both `analyticsHost` and `host_permissions` with your own instance URL.
* **Every pageview shows the extension ID as hostname**: expected. Extension pages live on `chrome-extension://<id>`; use `rybbit.pageview("/name")` for readable paths.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Circle (/de/docs/guides/circle)





Circle has a **Code snippets** setting that injects custom code into the `<head>` of every page in your community, so the snippet goes there once and covers public pages and logged-in member pages alike.

<Callout type="info">
  Custom CSS/JavaScript snippets are included on all current Circle plans (Professional, Business and Circle Plus).
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Circle [#add-the-snippet-to-circle]

    1. Open your community as an admin and go to **Settings**.
    2. Open **Code snippets**.
    3. Paste the snippet into the **Head code snippets** field.
    4. Click **Save**. Changes apply to the whole community immediately; there is no publish step.

    Circle's own help article for this setting is [Custom code snippets](https://help.circle.so/p/administration/site-management/custom-code-snippets).

    Circle is a single-page app: after the first load, navigating between spaces, posts and courses changes the URL without a full reload. The script tracks these client-side route changes automatically, so each space and post shows up as its own pageview.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Custom domain**: the same head code is served on `yourcommunity.circle.so` and on your custom domain. If both hostnames are in use, keep them under one site in Rybbit so sessions are not split.
* **Post embeds**: custom HTML embedded inside a post is scoped to that post. Put the snippet in head code snippets, not in a post.
* **Nothing tracked while logged in as admin**: Circle applies head code to admins too, so check that your own IP or user is not excluded in Rybbit's site settings before assuming the snippet is missing.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ClickFunnels (/de/docs/guides/clickfunnels)





ClickFunnels 2.0 has a **Header Code** field at three levels: **Site Settings** for the whole workspace, **Funnel settings** for every page in one funnel, and the page editor for a single page. Add the snippet at the widest level you want tracked and leave the narrower ones empty so it is not loaded twice.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ClickFunnels [#add-the-snippet-to-clickfunnels]

    <Tabs items="[&#x22;Whole site&#x22;, &#x22;One funnel&#x22;, &#x22;One page&#x22;]">
      <Tab>
        1. In your workspace, open the **Site & Blog** app in the left menu and click **Site Settings**.
        2. Paste the snippet into **Header Code**.
        3. Save.

        This applies to every page in the workspace: funnel pages, store pages, courses, blog posts and site pages.
      </Tab>

      <Tab>
        1. Open **Funnels** and click the **Settings** gear next to the funnel (or the **Settings** button in the top-right of the funnel workflow editor).
        2. Paste the snippet into **Head Code**.
        3. Click **Update Funnel**.

        The code loads on every page of that funnel only.
      </Tab>

      <Tab>
        1. Open the page in the page editor.
        2. Go to **Settings > Tracking Code** and paste the snippet into **Header Code**.
        3. Click **Save**.

        The code loads on this page only.
      </Tab>
    </Tabs>

    Save, then open the live page URL to test: header code does not run inside the page editor.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Duplicate pageviews**: the snippet is present at more than one level (site and funnel, or funnel and page). Keep a single copy.
* **Snippet not in the page source**: check which level you pasted it at. Site Settings covers the workspace, funnel settings cover that funnel's pages only, and the page editor covers one page.
* **jQuery**: ClickFunnels pages already include jQuery, so do not load it again in the same header code block; a second copy can break page scripts.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Contentful (/de/docs/guides/contentful)





Contentful is a headless CMS: it stores content and delivers it over its APIs, but never renders your pages. The tracking snippet therefore goes into the frontend that consumes Contentful, not into Contentful itself.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Contentful [#add-the-snippet-to-contentful]

    <Callout type="info">
      Contentful has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Contentful.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Contentful frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby), which pairs with the official `gatsby-source-contentful` plugin
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Editor previews count as visits**: Contentful's content preview URLs open a preview or draft build of your frontend. Register that deployment as a separate site in Rybbit, or leave the snippet out of preview builds, so editors' previews are not mixed into your production data.
* **The Contentful web app is not tracked**: the snippet only runs on your frontend, so time spent editing in Contentful never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Craft CMS (/de/docs/guides/craft-cms)





Craft CMS renders pages from Twig templates in the `templates/` folder, so the snippet goes into the base template that your section templates extend. A fresh `craftcms/craft` project ships a single `templates/index.twig` containing the full HTML document; most projects move that boilerplate into a base template and `{% extends %}` it.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Craft CMS [#add-the-snippet-to-craft-cms]

    1. Open the template that owns your `<head>`. In a fresh install that is `templates/index.twig`; in a project with a base template it is the underscore-prefixed file every page extends, such as `templates/_layout.twig`.
    2. Add the tag before `</head>`:

    ```twig title="templates/_layout.twig"
    <!DOCTYPE html>
    <html lang="{{ currentSite.language }}">
    <head>
        <meta charset="utf-8">
        <title>{{ siteName }}</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        {% block content %}{% endblock %}
    </body>
    </html>
    ```

    3. Every section template that extends the base template now loads the script:

    ```twig title="templates/blog/_entry.twig"
    {% extends "_layout" %}

    {% block content %}
        <h1>{{ entry.title }}</h1>
        {{ entry.body }}
    {% endblock %}
    {% endraw %}
    ```

    To keep the site ID out of templates and vary it per environment, read it from `.env` with `{{ getenv('RYBBIT_SITE_ID') }}`, or store it in a Global Set and use `{{ settings.rybbitSiteId }}`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Template caching**: if you wrap the head in `{% cache %}` tags, the change appears only after the cache expires or you run `php craft clear-caches/all`.
* **Live Preview counts as visits**: the control panel's Live Preview renders your template in an iframe with `x-craft-live-preview` in the query string. Wrap the tag in `{% if not craft.app.request.isPreview %}` to leave editors' previews out of your data.
* **Control panel is not tracked**: `/admin` uses Craft's own templates, so the snippet never runs there.
* **Multiple base templates**: if some sections extend a different base (for example `_layout-landing.twig`), add the tag to each one, or move it into a partial and `{% include %}` it from every base.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Discourse (/de/docs/guides/discourse)





Discourse adds site-wide code through **theme components**. A component has an editable `</head>` section that Discourse injects into every page and, because Discourse ships a strict Content Security Policy, it stamps the required nonce onto script tags placed there. No server access or plugin is needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Discourse [#add-the-snippet-to-discourse]

    1. In the admin sidebar open **Appearance → Themes and components** (older versions: **Admin → Customize → Themes**).
    2. On the **Components** tab click **Install**, choose **Create new**, name it "Rybbit Analytics", make sure the type is **Component** and click **Create**.
    3. Click **Edit CSS/HTML**, stay on the **Common*&#x2A; tab and open the &#x2A;*`</head>`** section (not **Header**, which is the visible page header).
    4. Paste the snippet and click **Save**.
    5. Back on the component page, add your active theme under **Include component on these themes** so the component is enabled.

    Discourse is a single-page app: after the first load, topics and categories open without a full page reload. The tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`, so those navigations are recorded as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Component saved but the script is missing from the page source**: the component is not attached to the active theme. Add the theme under **Include component on these themes**, or add the component from the theme's **Included components** list.
* **Script tag present but blocked**: check the browser console for a CSP error. Scripts added through the `</head>` section receive Discourse's nonce automatically; scripts injected any other way (for example from a plugin's raw HTML) do not.
* **Only the first pageview is recorded**: the **SPA Navigation** setting is off for the site in your Rybbit dashboard. Turn it on under Site Settings.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Django (/de/docs/guides/django)





Django pages extend a base template, so the snippet goes into the `<head>` of that base template. Put the site ID in `settings.py`, read from an environment variable, and pass it to templates with a small context processor so no template hard-codes the ID.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Django [#add-the-snippet-to-django]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to `settings.py`, reading from the environment:

    ```python filename="settings.py"
    import os

    RYBBIT_INSTANCE_URL = os.environ.get("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
    RYBBIT_SITE_ID = os.environ.get("RYBBIT_SITE_ID", "")
    ```

    Set `RYBBIT_SITE_ID=YOUR_SITE_ID` in your production environment (or your `.env` file if you load one with django-environ or python-dotenv).

    #### Expose the values to templates [#expose-the-values-to-templates]

    Create a context processor that adds both settings to every template context:

    ```python filename="myproject/context_processors.py"
    from django.conf import settings


    def rybbit(request):
        return {
            "RYBBIT_INSTANCE_URL": settings.RYBBIT_INSTANCE_URL,
            "RYBBIT_SITE_ID": settings.RYBBIT_SITE_ID,
        }
    ```

    Register it under `TEMPLATES` in `settings.py`:

    ```python filename="settings.py"
    TEMPLATES = [
        {
            "BACKEND": "django.template.backends.django.DjangoTemplates",
            "DIRS": [BASE_DIR / "templates"],
            "APP_DIRS": True,
            "OPTIONS": {
                "context_processors": [
                    "django.template.context_processors.request",
                    "django.contrib.auth.context_processors.auth",
                    "django.contrib.messages.context_processors.messages",
                    "myproject.context_processors.rybbit",
                ],
            },
        },
    ]
    ```

    #### Add the tag to your base template [#add-the-tag-to-your-base-template]

    Open the template that every page extends, usually `templates/base.html`, and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My Site{% endblock %}</title>

        {% if RYBBIT_SITE_ID %}
        <script src="{{ RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ RYBBIT_SITE_ID }}" defer></script>
        {% endif %}
    </head>
    ```

    The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable.

    Pages that do not `{% extends "base.html" %}` (for example a separate admin or landing template) need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: settings are read at startup, so restart the server (or your WSGI/ASGI workers) after changing `RYBBIT_SITE_ID`. Confirm the context processor path matches your project package name.
* **Template rendered without a request**: context processors only run for templates rendered with a `RequestContext`, which `render()` and class-based views provide. `Template.render()` without a request has no `RYBBIT_SITE_ID` and the guard hides the tag.
* **Content Security Policy**: if you use django-csp, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Docusaurus (/de/docs/guides/docusaurus)





Docusaurus has a `scripts` option in `docusaurus.config.js` that adds a `<script>` tag to the `<head>` of every page, so no theme swizzling is needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Docusaurus [#add-the-snippet-to-docusaurus]

    Open `docusaurus.config.js` (or `docusaurus.config.ts`) at the root of your project and add the script to the `scripts` array:

    ```javascript filename="docusaurus.config.js"
    /** @type {import('@docusaurus/types').Config} */
    const config = {
      // ... title, url, baseUrl, presets, themeConfig

      scripts: [
        {
          src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
          defer: true,
        },
      ],
    };

    module.exports = config;
    ```

    If you already manage tags through `headTags`, this form is equivalent:

    ```javascript filename="docusaurus.config.js"
    headTags: [
      {
        tagName: "script",
        attributes: {
          src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
          defer: "true",
        },
      },
    ],
    ```

    Rebuild with `npm run build` and deploy. The tag is not hot-reloaded into a running `npm run start` session until you restart it.

    <Callout type="info">
      Docusaurus builds a single-page app on React Router. Rybbit detects client-side route changes and records them as pageviews, so no extra code is needed for navigation.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Docusaurus pages are React, so you can fire events from a component and use it in MDX:

```jsx filename="src/components/TrackedButton.jsx"
import React from "react";

export default function TrackedButton({ children, eventName, eventData }) {
  const handleClick = () => {
    window.rybbit?.event(eventName, eventData);
  };

  return (
    <button onClick={handleClick} className="button button--primary">
      {children}
    </button>
  );
}
```

```mdx
import TrackedButton from "@site/src/components/TrackedButton";

<TrackedButton eventName="learn_more_clicked" eventData={{ page: "introduction" }}>
  Learn more
</TrackedButton>
```

For site-wide listeners, use a [client module](https://docusaurus.io/docs/advanced/client-modules). `onRouteDidUpdate` runs after every navigation once the DOM is ready:

```javascript filename="src/client-modules/rybbit-events.js"
export function onRouteDidUpdate() {
  document.querySelectorAll('a[target="_blank"]').forEach((link) => {
    link.addEventListener("click", () => {
      window.rybbit?.event("external_link_click", { href: link.href });
    });
  });
}
```

Register it in `docusaurus.config.js` under `clientModules: [require.resolve("./src/client-modules/rybbit-events.js")]`. Client modules also run during server-side rendering, so guard any `window` access.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Drupal (/de/docs/guides/drupal)





The [Rybbit module](https://www.drupal.org/project/rybbit) on Drupal.org adds the tracking script to every page and can pass logged-in user details to Rybbit, so you enter a Site ID instead of editing your theme. It requires Drupal 10.3 or later.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Drupal [#add-the-snippet-to-drupal]

    <Tabs items="[&#x22;Rybbit module&#x22;, &#x22;Theme template&#x22;]">
      <Tab>
        1. Install and enable the module:

           ```bash
           composer require drupal/rybbit
           drush en rybbit
           ```

        2. Go to **Configuration → Web services → Rybbit analytics** (`/admin/config/services/rybbit`). Your account needs the *administer rybbit* permission.

        3. Enter your **Site ID** and save.

        Optional settings on the same page:

        * **Script URL**: defaults to Rybbit cloud. Point it at your own instance if you self-host Rybbit.
        * **Visibility**: restrict tracking by role or by page path, each in include or exclude mode.
        * **Identify logged-in users**: calls `identify()` with the user's UUID by default, and sends traits you define as key/value pairs. `username`, `name` and `email` are recognised trait names.
        * The module also exposes hooks for altering the sitewide and per-user tracking data from your own module.
      </Tab>

      <Tab>
        If you cannot install contributed modules, copy `core/modules/system/templates/html.html.twig` into your theme's `templates` folder and add the snippet just before `</head>`:

        ```twig
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Clear caches afterwards so Drupal picks up the new template.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Script missing after saving settings**: pages are served from Drupal's page cache. Clear caches with `drush cr` or **Configuration → Development → Performance → Clear all caches**.
* **Visitors are tracked but you are not**: check the role and path visibility settings on the module page. Excluding the administrator role is a common setup.
* **Logged-in users appear anonymous**: enable **Identify logged-in users** in the module settings; without it Drupal accounts are tracked like any other visitor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Duda (/de/docs/guides/duda)





Duda has a site-wide **Header HTML** panel in the site settings with two fields: **Head HTML**, printed inside `<head>` on every page, and **Body End HTML**, printed before `</body>`. The snippet goes into Head HTML, and the site must be republished for it to reach the live site.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Duda [#add-the-snippet-to-duda]

    1. In the editor's side panel, click **More**, then **Settings**.
    2. Click **Header HTML**.
    3. Paste the snippet into **Head HTML** and click **Save**.
    4. **Republish** the site. Saved header code shows in the editor and preview, but the live site is only updated on republish.

    Head HTML accepts `<script>`, `<link>` and `<meta>` tags; anything else is stripped on save. The tracking snippet is a single `<script>` tag, so it is kept.

    To limit tracking to one page instead, open that page's **settings** (gear icon), click **SEO** and paste the snippet into that page's **Header HTML**.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the live page source**: the site was not republished. Republish after every change to Header HTML.
* **Code disappears after saving**: Head HTML strips tags other than `<script>`, `<link>` and `<meta>`. Paste only the script tag, without wrapping HTML or comments.
* **Consent management app in use**: Duda loads Head HTML before consent banners can intercept it. If you need the tracker gated by consent, put the snippet in **Body End HTML** instead, where the consent app can control it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ecwid (/de/docs/guides/ecwid)





An Ecwid by Lightspeed store runs either on Ecwid's hosted **Instant Site** or embedded in a page on another platform. On Instant Site the snippet goes into the site's header code setting; for an embedded store it goes into the `<head>` of the host site, and the storefront Ecwid renders inside that page is tracked with it.

<Callout type="warn">
  Custom code on Instant Site is available on the **Venture**, **Business** and **Unlimited** plans. The free Starter plan has no custom code fields.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ecwid [#add-the-snippet-to-ecwid]

    <Tabs items="[&#x22;Instant Site&#x22;, &#x22;Embedded store&#x22;]">
      <Tab>
        1. From your Ecwid admin, go to **Website** (or **Overview → Manage Instant Site**).
        2. Scroll down to **SEO settings** and click **Add Code** under **Header meta tags and site verification**.
        3. Paste the snippet and save.
        4. Reload your Instant Site in the browser; there is no separate publish step for this setting.

        The **Custom JavaScript code** field under **Advanced website settings** on the same page also works, but it prints code at the end of `<body>`, so prefer the header field.
      </Tab>

      <Tab>
        The store is rendered by Ecwid's embed script inside your own page, so add the snippet to the `<head>` of the host site with that platform's method. See the [integration guides](/docs/guides) for WordPress, Wix, Squarespace, Webflow and others.

        One snippet covers the whole store: product pages, cart and checkout all render inside the same host page.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Ecwid's storefront JavaScript API fires `Ecwid.OnOrderPlaced` with the order right after a customer places it. Add this where the `Ecwid` object already exists: on Instant Site, under **Advanced website settings → Custom JavaScript code**; on an embedded store, after the Ecwid embed script on the host page.

```html
<script>
Ecwid.OnAPILoaded.add(function () {
  Ecwid.OnOrderPlaced.add(function (order) {
    window.rybbit.event('purchase', {
      transaction_id: order.vendorNumber,
      value: order.total,
      tax: order.tax,
      shipping: order.shipping,
      items: order.items.map(function (item) {
        return { item_id: item.sku, item_name: item.name, price: item.price, quantity: item.quantity };
      })
    });
  });
});
</script>
```

`vendorNumber` is the order number customers see in emails; `orderNumber` is Ecwid's internal ID. Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.

Ecwid also has a **Custom tracking code on Order Confirmation page** field under **Settings → General → Tracking & Analytics** (same plans as above). Code there runs on the `/checkout/order-confirmation` page and can use Ecwid's template variables when wrapped in `<#noescape>`:

```html
<script>
<#noescape>
document.addEventListener('DOMContentLoaded', function () {
  window.rybbit.event('purchase', { transaction_id: "${order.number}", value: ${order.total} });
});
</#noescape>
</script>
```

Use one method or the other, not both, or every order is counted twice.

## Troubleshooting [#troubleshooting]

* **No Add Code button under SEO settings**: the store is on the Starter plan. Custom code needs Venture or higher.
* **`Ecwid is not defined`**: the purchase snippet ran before Ecwid's script. Move it below the embed script, or keep it in the Instant Site **Custom JavaScript code** field, which runs at the end of the page.
* **Embedded store, no pageviews**: the snippet belongs to the host site, not to Ecwid. Check the host page's source for `script.js?siteId=`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Electron (/de/docs/guides/electron)





An Electron renderer is a Chromium page, so Rybbit runs in it the same way it runs in a browser. For a renderer built with a bundler (Vite, webpack, the Electron Forge templates) install the `@rybbit/js` SDK and initialise it in the renderer entry file; for a plain HTML renderer put the snippet in the `<head>` of the HTML file the window loads. In both cases allow `https://app.rybbit.io` in the renderer's Content Security Policy.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Electron [#add-the-snippet-to-electron]

    <Tabs items="[&#x22;@rybbit/js SDK&#x22;, &#x22;Script tag&#x22;]">
      <Tab>
        The SDK is bundled with your renderer code, so nothing is loaded from a CDN at runtime and `script-src 'self'` stays intact.

        1. Install the package in your project:

        ```bash
        npm install @rybbit/js
        ```

        2. Initialise it once in the renderer entry file, before any other tracking call:

        ```js title="src/renderer.js"
        import rybbit from "@rybbit/js";

        await rybbit.init({
          analyticsHost: "https://app.rybbit.io/api",
          siteId: "YOUR_SITE_ID",
        });
        ```

        3. Allow the analytics host in `connect-src`. Electron recommends a CSP for every renderer; when the renderer is loaded from a file, HTTP headers are not available, so use the meta tag:

        ```html title="src/index.html"
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'self'; connect-src 'self' https://app.rybbit.io"
        />
        ```
      </Tab>

      <Tab>
        Paste the snippet into the `<head>` of the renderer HTML and allow the host in both `script-src` (the script itself) and `connect-src` (its requests):

        ```html title="src/index.html"
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'self'; script-src 'self' https://app.rybbit.io; connect-src 'self' https://app.rybbit.io"
        />
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        If you set the CSP from the main process with `session.defaultSession.webRequest.onHeadersReceived` instead, add the same two sources there.
      </Tab>
    </Tabs>

    Both methods track in-app navigation without extra code: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so history-mode and hash-mode routers are covered.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Requests are blocked on the `file://` origin**: Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only. A renderer opened with `win.loadFile()` runs on the `file://` origin and sends `Origin: null`, so Chromium blocks the `POST` to `/api/track` before it leaves the app. The same applies to custom schemes registered with `protocol.handle()`. Load the renderer over http(s) with `win.loadURL()` (your dev server in development, a hosted or locally served build in production) and tracking works.
* **Console shows a CSP violation**: the message names the directive that blocked the request. Add `https://app.rybbit.io` to that directive; `connect-src` covers the SDK, and the script tag also needs `script-src`.
* **Hostname is empty in the dashboard**: pageviews report the renderer's `window.location.hostname`, which is empty for `file://` pages. Filter by site rather than hostname.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Eleventy (/de/docs/guides/eleventy)





Eleventy renders every page through a layout in `_includes/`, so the snippet goes in your base layout's `<head>`. Keep the site ID in a global data file under `_data/` so the layout stays free of hard-coded values.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Eleventy [#add-the-snippet-to-eleventy]

    1. Create `_data/rybbit.json` (create the `_data/` directory if it does not exist). Every template can then read it as `rybbit`. Change `instanceUrl` only if you self-host:

       ```json title="_data/rybbit.json"
       {
         "siteId": "YOUR_SITE_ID",
         "instanceUrl": "https://app.rybbit.io"
       }
       ```

    2. Open your base layout and add the tag inside `<head>`. The `eleventy.env.runMode` check keeps the script out of `--serve` and `--watch` runs, so local development is not tracked; the `rybbit.siteId` check keeps it out of builds with no ID configured.

    <Tabs items="[&#x22;Nunjucks&#x22;, &#x22;Liquid&#x22;]">
      <Tab value="Nunjucks">
        ```html title="_includes/base.njk"
        <head>
          ...
          {% if eleventy.env.runMode == "build" and rybbit.siteId %}
            <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>

      <Tab value="Liquid">
        ```html title="_includes/base.liquid"
        <head>
          ...
          {% if eleventy.env.runMode == "build" and rybbit.siteId %}
            <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>
    </Tabs>

    3. Build and deploy the generated `_site/` directory:

       ```bash
       npx @11ty/eleventy
       ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `npx @11ty/eleventy --serve` sets `runMode` to `serve`, so the guard removes the tag. Check the output of a plain build instead.
* **Eleventy 1.x**: `eleventy.env.runMode` was added in Eleventy 2.0. On older versions drop the `runMode` condition and keep only the `rybbit.siteId` check.
* **Custom data directory**: if your config sets `dir.data`, put `rybbit.json` in that directory instead of `_data/`.
* **Several layouts**: a page only gets the tag if its layout chain ends in the layout you edited. Pages with `layout: none` or a different base layout need the tag added there too.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ember (/de/docs/guides/ember)





An Ember app has one HTML shell that every route renders into. Apps created with the current Vite-based `ember new` blueprint keep it at `index.html` in the project root; classic ember-cli apps keep it at `app/index.html`. Paste the snippet into the `<head>` of that file.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ember [#add-the-snippet-to-ember]

    Open `index.html` (or `app/index.html` in a classic ember-cli app) and paste the snippet inside `<head>`, after the `{{content-for "head"}}` placeholder:

    ```handlebars title="index.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8">
        <title>MyApp</title>
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        {{content-for "head"}}

        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

        <link integrity="" rel="stylesheet" href="/@embroider/virtual/vendor.css">
        <link integrity="" rel="stylesheet" href="/@embroider/virtual/app.css">

        {{content-for "head-footer"}}
      </head>
      <body>
        {{content-for "body"}}
        ...
        {{content-for "body-footer"}}
      </body>
    </html>
    ```

    Keep the `{{content-for}}` placeholders in place; the build fills them in. Route transitions made by Ember's router (the default `history` location type) are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a component action. Guard the call so a blocked or still-loading script does not throw.

```js title="app/components/signup-button.gjs"
import Component from "@glimmer/component";
import { on } from "@ember/modifier";

export default class SignupButton extends Component {
  trackSignup = () => {
    if (window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  <template>
    <button type="button" {{on "click" this.trackSignup}}>Sign up</button>
  </template>
}
```

## Troubleshooting [#troubleshooting]

* **`index.html` is also used by the test runner**: `tests/index.html` is a separate file. Do not add the snippet there, or test runs send pageviews to your dashboard.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# FastAPI (/de/docs/guides/fastapi)





FastAPI serves HTML through `Jinja2Templates`, so the snippet goes into the `<head>` of the base template your pages extend. Keep the site ID in a `pydantic-settings` class and register it as a Jinja global so every template can render the tag without passing it through each route.

<Callout type="info">
  The tracking script runs in a browser, so it only applies to routes that return template-rendered HTML. JSON endpoints have nothing for it to track.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to FastAPI [#add-the-snippet-to-fastapi]

    #### Configure the site ID [#configure-the-site-id]

    Install `pydantic-settings` and `jinja2` if you have not already:

    ```bash
    pip install pydantic-settings jinja2
    ```

    Define the settings, reading from the environment and an optional `.env` file:

    ```python filename="config.py"
    from pydantic_settings import BaseSettings, SettingsConfigDict


    class Settings(BaseSettings):
        model_config = SettingsConfigDict(env_file=".env")

        rybbit_instance_url: str = "https://app.rybbit.io"
        rybbit_site_id: str = ""


    settings = Settings()
    ```

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    #### Register the values with Jinja [#register-the-values-with-jinja]

    `Jinja2Templates` exposes its environment as `templates.env`, so add the settings as globals once, next to where you create the templates object:

    ```python filename="main.py"
    from fastapi import FastAPI, Request
    from fastapi.responses import HTMLResponse
    from fastapi.templating import Jinja2Templates

    from config import settings

    app = FastAPI()
    templates = Jinja2Templates(directory="templates")
    templates.env.globals["rybbit_instance_url"] = settings.rybbit_instance_url
    templates.env.globals["rybbit_site_id"] = settings.rybbit_site_id


    @app.get("/", response_class=HTMLResponse)
    async def index(request: Request):
        return templates.TemplateResponse(request=request, name="index.html")
    ```

    #### Add the tag to your base template [#add-the-tag-to-your-base-template]

    Open the template your pages extend, usually `templates/base.html`, and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My App{% endblock %}</title>

        {% if rybbit_site_id %}
        <script src="{{ rybbit_instance_url }}/api/script.js?siteId={{ rybbit_site_id }}" defer></script>
        {% endif %}
    </head>
    ```

    The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable. Templates that do not extend the base need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `Settings()` reads the environment when the module is imported, so restart Uvicorn (or your process manager) after changing `RYBBIT_SITE_ID`.
* **Several `Jinja2Templates` instances**: globals are per environment. If routers create their own `Jinja2Templates`, set the globals on each, or share one instance from a module.
* **Content Security Policy**: if middleware sets one, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Flask (/de/docs/guides/flask)





Flask renders Jinja templates, and most apps extend a shared base layout, so the snippet goes into that layout's `<head>`. Flask exposes `app.config` to every template as `config`, so store the site ID there and reference it from the template.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Flask [#add-the-snippet-to-flask]

    #### Configure the site ID [#configure-the-site-id]

    Flask loads any environment variable prefixed with `FLASK_` into `app.config` when you call `from_prefixed_env()`. Set the values in your environment (`flask run` also reads a `.env` file when python-dotenv is installed):

    ```bash filename=".env"
    FLASK_RYBBIT_INSTANCE_URL=https://app.rybbit.io
    FLASK_RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then load them where you create the app:

    ```python filename="app.py"
    from flask import Flask, render_template

    app = Flask(__name__)
    app.config.setdefault("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
    app.config.from_prefixed_env()


    @app.route("/")
    def index():
        return render_template("index.html")
    ```

    `from_prefixed_env()` parses values as JSON where it can, so a numeric site ID arrives as an `int`. It renders the same in the template.

    If you keep configuration in a Python file or class instead, add `RYBBIT_INSTANCE_URL` and `RYBBIT_SITE_ID` there and load it with `app.config.from_object()`.

    #### Add the tag to your base layout [#add-the-tag-to-your-base-layout]

    Open the template that your pages extend, usually `templates/base.html` (or `templates/layout.html`), and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My App{% endblock %}</title>

        {% if config.RYBBIT_SITE_ID %}
        <script src="{{ config.RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ config.RYBBIT_SITE_ID }}" defer></script>
        {% endif %}
    </head>
    ```

    `config` is part of Flask's standard template context, so no context processor is needed. The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is unset, so local development is not tracked unless you set the variable.

    Templates that do not extend the base layout need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `from_prefixed_env()` reads the environment when the app is created, so restart the server after changing `FLASK_RYBBIT_SITE_ID`. Check `app.config["RYBBIT_SITE_ID"]` in `flask shell`.
* **Macros imported into other templates**: `config` is added to the render context, not to imported templates. A macro that outputs the tag must be imported `with context`.
* **Content Security Policy**: if you set one with Flask-Talisman or similar, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `FLASK_RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Flutter web (/de/docs/guides/flutter-web)





A Flutter web app is served from the `web/index.html` template in your project, which `flutter build web` copies to `build/web/index.html`. The snippet goes in that file's `<head>`. Flutter draws the UI into a canvas rather than DOM elements, so pageviews and manual events work as usual while anything that inspects the DOM does not.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Flutter web [#add-the-snippet-to-flutter-web]

    1. Open `web/index.html` in your Flutter project.
    2. Paste the snippet inside `<head>`, above the `flutter_bootstrap.js` script that Flutter generates:

    ```html title="web/index.html"
    <head>
      <meta charset="UTF-8" />
      <title>My App</title>
      <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    ```

    3. Rebuild with `flutter build web` and deploy the `build/web` folder.

    Navigation is tracked automatically with either URL strategy. Flutter's default hash strategy writes routes as `/#/settings`, and the tracker listens for `hashchange` and records `#/settings` as the path `/settings`. With `usePathUrlStrategy()` the Navigator uses the History API, and the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Flutter widgets are not HTML elements, so `data-rybbit-event` attributes have nothing to attach to. Call `window.rybbit.event()` from Dart through `dart:js_interop` instead:

```dart title="lib/analytics.dart"
import 'dart:js_interop';

@JS('rybbit.event')
external void _rybbitEvent(String name, [JSAny? properties]);

void trackEvent(String name, [Map<String, Object?>? properties]) {
  _rybbitEvent(name, properties?.jsify());
}
```

```dart
ElevatedButton(
  onPressed: () {
    trackEvent('signup_click', {'plan': 'pro'});
  },
  child: const Text('Sign up'),
)
```

Guard the call with `kIsWeb` if the same code also compiles for mobile or desktop targets.

## Troubleshooting [#troubleshooting]

* **Clicks, outbound links and session replay show nothing**: the CanvasKit and Skwasm renderers paint into a single `<canvas>`, so DOM-based features (`data-rybbit-event` attributes, outbound-link tracking, button-click autocapture, session replay) have no elements to observe. Use the Dart interop above for events.
* **Deep links 404 after switching to `usePathUrlStrategy()`**: path URLs need the web server to rewrite every route to `index.html`; the Flutter dev server does this for you, production hosting must be configured.
* **`rybbit` is undefined in Dart**: the snippet is `defer`red, so it is not ready during `main()`. Send events from user interactions, not from app start-up.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Framer (/de/docs/guides/framer)





Framer has a **Custom Code** section in the site settings that injects HTML into the `<head>` of every published page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Framer [#add-the-snippet-to-framer]

    1. Open your Framer project and go to **Site Settings → General**.
    2. Scroll to **Custom Code**.
    3. Paste the snippet into the **Start of `<head>` tag** field (End of `<head>` works too).
    4. Click **Save**, then **Publish**. Custom code only reaches the live site on publish.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Use a **Code Override** to send events from any element in the canvas.

1. Select the element, open **Overrides*&#x2A; in the properties panel, and click **+ File** to create an override file such as `RybbitOverrides.tsx`.
2. Add an override that wraps the element's click handler:

```tsx
// RybbitOverrides.tsx
import type { ComponentType } from "react";

export function withRybbitClick(Component: ComponentType): ComponentType {
  return (props) => {
    const handleClick = () => {
      window.rybbit?.event("cta_click", { label: props.text ?? "cta" });
      props.onClick?.();
    };
    return <Component {...props} onClick={handleClick} />;
  };
}
```

3. Back in the properties panel, pick the file and apply `withRybbitClick` to the element.

The same `window.rybbit.event()` call works inside a **Code Component**.

## Troubleshooting [#troubleshooting]

* **Navigation between pages is not tracked**: Framer sites navigate client-side and the script detects those URL changes. If a view changes without the URL changing, call `window.rybbit.pageview()` from an override when it appears.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Fumadocs (/de/docs/guides/fumadocs)





Fumadocs is a documentation framework for Next.js, so the snippet goes in the root layout, `app/layout.tsx`, rendered with `next/script` so it is on every page including the docs routes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Fumadocs [#add-the-snippet-to-fumadocs]

    Open `app/layout.tsx` and render the `Script` component inside `<body>`, next to the `RootProvider` that Fumadocs already puts there:

    ```tsx title="app/layout.tsx"
    import { RootProvider } from "fumadocs-ui/provider/next";
    import Script from "next/script";
    import type { ReactNode } from "react";

    export default function Layout({ children }: { children: ReactNode }) {
      return (
        <html lang="en" suppressHydrationWarning>
          <body className="flex flex-col min-h-screen">
            <RootProvider>{children}</RootProvider>
            <Script
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    Use the root layout, not `app/docs/layout.tsx`: the docs layout only wraps pages under `/docs`, so a landing page outside it would be missed.

    Client-side navigation between docs pages is recorded as pageviews automatically. The [Next.js guide](/docs/guides/react/next-js) covers the `Script` component, custom events from client components and proxying through your own domain.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ghost (/de/docs/guides/ghost)





Ghost has a built-in **Code injection** setting that adds HTML to the `<head>` of every page, so no theme edits are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ghost [#add-the-snippet-to-ghost]

    1. Open **Ghost Admin** and click the **Settings** gear in the bottom left.
    2. Under **Advanced**, open **Code injection**.
    3. Paste the snippet into **Site header** and click **Save**.

    If you maintain your own theme instead, add the snippet to `default.hbs` just before `</head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Ghost(Pro) with a custom theme**: code injection still applies on top of the theme, so prefer it over editing `default.hbs`.
* **Member-only content**: pages behind the paywall are tracked like any other page for visitors who can view them.
* **Portal and newsletter previews** render in an iframe and are not tracked.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# GitBook (/de/docs/guides/gitbook)





GitBook does not let you add custom scripts to a published site, and its integration platform does not let third parties inject them either. This page explains what that means and what your options are.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to GitBook [#add-the-snippet-to-gitbook]

    <Callout type="warn">
      There is currently no supported way to load the Rybbit snippet on a GitBook-hosted site. The old **Custom scripts → Head** setting was removed, and GitBook's [integration scopes](https://gitbook.com/docs/developers/integrations/configurations) reserve `site:script:inject` for GitBook's own integrations: "Building integrations that inject JavaScript into a site or space is not possible at this time."
    </Callout>

    Your options:

    * **Use GitBook's built-in analytics.** The **Insights** section in the GitBook app reports page views and search terms for published sites without any script.
    * **Wait for a native integration.** A Rybbit integration would need GitBook to build or approve it. Ask GitBook support for it, and watch the [Rybbit roadmap](/docs/roadmap).
    * **Host the docs elsewhere.** [Docusaurus](/docs/guides/docusaurus), [Mintlify](/docs/guides/mintlify), [VitePress](/docs/guides/vitepress), [Starlight](/docs/guides/starlight) and [Fumadocs](/docs/guides/fumadocs) all take the snippet directly, and GitBook can export a space as Markdown to migrate.

    The rest of your site (marketing pages, app, blog) is unaffected: add the snippet there as usual so traffic from the docs is still attributed by referrer.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Google Tag Manager (/de/docs/guides/google-tag-manager)





Google Tag Manager loads Rybbit through a **Custom HTML** tag fired on **All Pages**, so nothing in your site's code changes. Events you already push to the `dataLayer` can be forwarded to Rybbit with a second tag.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Google Tag Manager [#add-the-snippet-to-google-tag-manager]

    1. Open your GTM container and go to **Tags → New**.
    2. Under **Tag Configuration**, choose **Custom HTML** and paste the snippet:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    3. Under **Triggering**, choose **All Pages** (the built-in Page View trigger).
    4. Name the tag, for example `Rybbit - Loader`, and click **Save**.
    5. Click **Submit** and publish the container version.

    <Callout type="warn">
      GTM rebuilds Custom HTML tags before injecting them and can drop non-standard attributes. Keep the site ID in the URL (`?siteId=`) as shown; the older `data-*` attribute form is not reliable here.
    </Callout>

    Use **Preview** mode to confirm the tag fires on page load before publishing.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Once the loader tag is published, `window.rybbit` is available to your own JavaScript and to other GTM tags.

#### Forward dataLayer events [#forward-datalayer-events]

If your site already pushes events like `dataLayer.push({ event: "signup" })`, one tag can forward them to Rybbit:

1. Create a **Custom Event** trigger. Set the event name to a regex such as `signup|purchase|add_to_cart` (tick **Use regex matching**).
2. Create a **Custom HTML** tag with that trigger:

```html
<script>
  if (window.rybbit) {
    window.rybbit.event("{{Event}}", {
      page: "{{Page Path}}",
      referrer: "{{Referrer}}"
    });
  }
</script>
```

`{{Event}}`, `{{Page Path}}` and `{{Referrer}}` are GTM built-in variables. Add a **Data Layer Variable** for any custom field you push (for example `plan`) and reference it the same way.

#### Use GTM's click and form triggers [#use-gtms-click-and-form-triggers]

The same pattern works with built-in **Click** and **Form Submission** triggers:

```html
<script>
  if (window.rybbit) {
    window.rybbit.event("cta_clicked", {
      text: "{{Click Text}}",
      url: "{{Click URL}}"
    });
  }
</script>
```

Enable the **Click Text** and **Click URL** built-in variables under **Variables → Configure**.

## Troubleshooting [#troubleshooting]

* **Event tag fires before Rybbit loads**: the loader script is deferred, so an event tag on the same page load may run first and hit the `if (window.rybbit)` guard. Open the event tag's **Advanced Settings → Tag Sequencing** and set the loader tag to fire before it, or trigger the event tag on **Window Loaded** instead of **Page View**.
* **Consent mode**: if your container gates tags on consent, add the loader tag to the same consent group as your other analytics tags, otherwise it never fires.
* **Tag shows in Preview but not live**: the container version was not published. Click **Submit** and publish.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hexo (/de/docs/guides/hexo)





Hexo 5 and later ship an injector API that adds HTML to the `<head>` of every generated page from a small file in your site's `scripts/` directory, so no theme edits are needed. Editing the theme's head partial is the fallback for older versions.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hexo [#add-the-snippet-to-hexo]

    <Tabs items="[&#x22;Injector script&#x22;, &#x22;Theme layout&#x22;]">
      <Tab value="Injector script">
        1. Add your site ID to the site `_config.yml` at the root of your project (not the theme config). `instance_url` is only needed if you self-host:

           ```yaml title="_config.yml"
           rybbit:
             site_id: "YOUR_SITE_ID"
             instance_url: "https://app.rybbit.io"
           ```

        2. Create `scripts/rybbit.js` (create the `scripts/` directory if it does not exist). Hexo loads every file in this directory at startup with the `hexo` object in scope:

           ```javascript title="scripts/rybbit.js"
           const { site_id: siteId, instance_url: instanceUrl = "https://app.rybbit.io" } =
             hexo.config.rybbit || {};

           if (siteId) {
             hexo.extend.injector.register(
               "head_end",
               `<script src="${instanceUrl}/api/script.js?siteId=${siteId}" defer></script>`
             );
           }
           ```

           `head_end` places the tag right before `</head>`. With no third argument the injector applies to every page type.
      </Tab>

      <Tab value="Theme layout">
        Open your theme's head partial and paste the snippet before `</head>`. For the default Landscape theme that file is `themes/landscape/layout/_partial/head.ejs`; other themes keep an equivalent partial under `layout/`.

        ```html title="themes/landscape/layout/_partial/head.ejs"
          ...
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Theme updates overwrite this file, so prefer the injector when your Hexo version supports it.
      </Tab>
    </Tabs>

    Regenerate and deploy the `public/` directory:

    ```bash
    hexo clean && hexo generate
    ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **`hexo.extend.injector` is undefined**: the injector API arrived in Hexo 5.0. Check `hexo version` and upgrade, or use the theme layout method.
* **Tag missing after adding the script**: run `hexo clean` before `hexo generate`; Hexo caches rendered output in `db.json` and can serve stale pages.
* **Local previews are tracked**: `hexo server` runs the same injector as `hexo generate`. Leave `site_id` empty in a local copy of `_config.yml`, or accept the local pageviews.
* **Theme config vs site config**: `hexo.config` reads the root `_config.yml`, not `themes/<name>/_config.yml`. Put the `rybbit` block in the root file.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hostinger Website Builder (/de/docs/guides/hostinger)





Hostinger Website Builder has a **Custom code** integration in the website settings that adds code to every page. Script tags are placed at the end of `<body>` by default; a `data-render-head` attribute moves them into `<head>`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hostinger Website Builder [#add-the-snippet-to-hostinger-website-builder]

    1. Open your site in the builder and click &#x2A;*⋯** (More) at the top to open the website settings, then choose **Integrations**.
    2. Select **Custom code**.
    3. Paste the snippet with `data-render-head` added so it loads from `<head>`:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer data-render-head></script>
    ```

    4. Save the changes, then click **Update website** to publish. Custom code runs on the live site and in preview, not inside the editor.

    Without `data-render-head` the builder moves `<script>` tags to the end of `<body>`. The tracker still works there; the attribute only makes it load earlier.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **No requests to `script.js` in the editor**: expected. Integrations are injected into the published site only, so check the live URL or the preview.
* **Snippet saved but not in the page source**: the site was not updated after saving. Click **Update website**.
* **Site breaks after adding several snippets**: paste snippets one after another, never nested inside each other. If the page still fails, remove all custom code, update, and add the snippets back one at a time.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# htmx (/de/docs/guides/htmx)





htmx pages are plain server-rendered HTML, so the snippet goes in the `<head>` of your base layout next to the htmx script tag, in whichever template your server uses for the full-page response.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to htmx [#add-the-snippet-to-htmx]

    Open the template that renders the full HTML document (the one that already loads htmx) and paste the snippet inside `<head>`:

    ```html title="layout.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My htmx App</title>
        <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.10/dist/htmx.min.js"></script>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <main id="content" hx-boost="true">...</main>
      </body>
    </html>
    ```

    Only full-page responses need the tag. Partial responses that htmx swaps into the page must not include it, or the script is re-evaluated on every swap.

    Navigations that htmx records in browser history are tracked automatically as pageviews: `hx-push-url` and `hx-boost` call `history.pushState()`, `hx-replace-url` calls `history.replaceState()`, and the back and forward buttons fire `popstate`. All three are hooked by the tracker. A swap without `hx-push-url` leaves the URL unchanged and is not counted as a pageview; send a [custom event](/docs/track-events) for those interactions instead.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Use the `data-rybbit-event` attribute on the element that triggers the request. The tracker listens for clicks on `document`, so it also works on content that htmx swapped in after the page loaded:

```html
<button
  hx-post="/subscribe"
  hx-target="#form"
  data-rybbit-event="newsletter_subscribe"
  data-rybbit-prop-plan="free"
>
  Subscribe
</button>
```

To record an event when the server has actually processed the request, listen for htmx's `htmx:afterRequest` event and call `window.rybbit.event()` from there.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# HubSpot (/de/docs/guides/hubspot)





HubSpot Content Hub (formerly CMS Hub) has a **Site header HTML** setting that injects code into the `<head>` of every website page, landing page, blog post and knowledge base article on a domain, so no template edits are needed. Individual pages can add or override code from the content editor.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to HubSpot [#add-the-snippet-to-hubspot]

    <Tabs items="[&#x22;Site header HTML&#x22;, &#x22;Single page&#x22;]">
      <Tab>
        This adds the snippet to all HubSpot-hosted content on a domain.

        1. In your HubSpot account, click the **settings** icon in the top navigation bar.
        2. In the left sidebar, go to **Content > Pages**.
        3. Use the **Choose a domain to edit its settings** dropdown to pick the domain, or stay on the default settings to apply the code to every domain.
        4. Paste the snippet into the **Site header HTML** field.
        5. Click **Save**.

        If a domain has **Override default settings** turned on, the default header code no longer applies to it. Add the snippet to that domain's own settings as well.
      </Tab>

      <Tab>
        Use this to track a single page, or when someone else controls the domain settings.

        1. Open **Content > Website Pages** (or **Landing Pages**, **Blog**, **Knowledge Base**) and click the page name to open the editor.
        2. Click the **Settings** menu, then select **Advanced**.
        3. Under **Additional code snippets**, paste the snippet into the **Head HTML** field.
        4. Click **Update** or **Publish**.

        Per-page head HTML is added on top of the site header HTML, so a page tracked by both methods loads the script twice. Pick one.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

HubSpot forms submit inside the page without a full reload, so track them with a custom event. Add `data-rybbit-event` to a call-to-action button, or listen for HubSpot's form-submitted message in a small script placed after the snippet:

```html
<script>
  window.addEventListener("message", function (event) {
    if (event.data.type === "hsFormCallback" && event.data.eventName === "onFormSubmitted") {
      window.rybbit.event("form_submitted", { formId: event.data.id });
    }
  });
</script>
```

See [Track custom events](/docs/track-events) for the event API.

## Troubleshooting [#troubleshooting]

* **Snippet missing on one domain**: the site header HTML is per domain. Check whether that domain has **Override default settings** enabled and add the snippet there.
* **Duplicate pageviews**: the same page has the snippet in both site header HTML and its own **Head HTML**. Remove one.
* **Editor and preview**: the content editor renders pages in an iframe with unpublished changes. Previews are tracked like any other visit if they load the script, so avoid checking analytics from the editor.
* **Quotes**: header HTML set at the domain level also loads on HubSpot quotes hosted on that domain.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hugo (/de/docs/guides/hugo)





Hugo builds every page from templates under `layouts/`, so the cleanest place for the snippet is a partial template that your base template includes on every page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hugo [#add-the-snippet-to-hugo]

    1. Add your site ID under `params` in your Hugo config (`hugo.toml`, or `config.toml` in older Hugo versions). `rybbitInstanceURL` is only needed if you self-host:

       ```toml title="hugo.toml"
       [params]
         rybbitSiteID = "YOUR_SITE_ID"
         rybbitInstanceURL = "https://app.rybbit.io"
       ```

    2. Create `layouts/partials/rybbit-analytics.html` (create the `layouts/partials/` directory if it does not exist):

       ```html title="layouts/partials/rybbit-analytics.html"
       {{ if and (not hugo.IsServer) .Site.Params.rybbitSiteID }}
         <script src="{{ .Site.Params.rybbitInstanceURL | default "https://app.rybbit.io" }}/api/script.js?siteId={{ .Site.Params.rybbitSiteID }}" defer></script>
       {{ end }}
       ```

       `not hugo.IsServer` skips the script during `hugo server`, so local development is not tracked. The `rybbitSiteID` check keeps the tag out of builds that have no ID configured.

    3. Include the partial from your base template, typically `layouts/_default/baseof.html`, inside `<head>`. If your theme owns `baseof.html`, copy it into your project's `layouts/_default/` first so the theme can be updated without losing the change; a theme footer partial such as `layouts/partials/footer.html` also works.

       ```html title="layouts/_default/baseof.html"
       <head>
         ...
         {{ partial "rybbit-analytics.html" . }}
       </head>
       ```

    4. Build with `hugo` and deploy the generated `public/` directory.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `hugo server` never emits it because of the `hugo.IsServer` guard. Check the output of a production `hugo` build instead.
* **Theme overrides**: a file at `layouts/_default/baseof.html` in your project takes precedence over the theme's copy, so make sure you edited the one Hugo actually renders.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Integration guides (/de/docs/guides)



Rybbit works on any site that can load a script tag. Each guide below shows exactly where the tracking snippet goes on that platform and how to confirm it is working.

Don't see your platform? Paste the snippet from **Site Settings → Tracking Script** into the `<head>` of every page, or follow the [tracking script](/docs/script) reference.

<GuideIndex />


# Instapage (/de/docs/guides/instapage)





Instapage takes custom scripts at two levels: **Workspace scripts** (under **Assets > Scripts**) apply to every page in a workspace, and each page also has its own **JavaScript** and **HTML/CSS** settings with a **Head** section. Custom HTML, CSS and JavaScript are included on all Instapage plans; Workspace scripts are limited to some subscriptions and show an upgrade prompt otherwise.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Instapage [#add-the-snippet-to-instapage]

    <Tabs items="[&#x22;Workspace scripts&#x22;, &#x22;Single page&#x22;]">
      <Tab>
        1. In the left menu, open **Assets**, then **Scripts**.
        2. Paste the snippet into the **Head** section.
        3. Above the editor, choose how it applies: option **A** adds it to every past and future page in the workspace; **B** leaves it off until you switch it on per page under **Scripts & Privacy**; **B + C** turns it on for all pages but lets you disable it per page.
        4. Click **Apply**.

        Workspace scripts load on the live URL before any page-level script, so the snippet is in place before other code on the page runs.
      </Tab>

      <Tab>
        1. Open the page in the builder and click **Settings** in the right sidebar.
        2. Open the **HTML/CSS** tab and paste the snippet into **Head**. (The **JavaScript** tab has the same three sections and wraps your code in `<script>` tags automatically; the snippet already has its own tag, so HTML/CSS is the simpler choice.)
        3. **Publish** the page. Custom code runs only on the live, published page, not in the editor or preview.
      </Tab>
    </Tabs>

    <Callout type="info">
      If you use Instapage's privacy compliance banner, put the snippet in the page's **Scripts & Privacy** section instead so it fires only after the visitor accepts.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: the page was saved but not republished. Custom code only reaches the live URL on publish.
* **Assets > Scripts shows an upgrade prompt**: Workspace scripts are not on your subscription. Add the snippet per page instead.
* **Duplicate pageviews**: the snippet is both a workspace script and a page-level script. Keep one copy.
* **Old version still served**: clear your browser cache after publishing; Instapage notes cached copies can outlive an update.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Jekyll (/de/docs/guides/jekyll)





Jekyll renders every page through a layout, usually `_layouts/default.html`. Put the snippet in an include file that the layout pulls in, or paste it into the layout directly.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Jekyll [#add-the-snippet-to-jekyll]

    <Tabs items="[&#x22;Include file&#x22;, &#x22;Layout file&#x22;]">
      <Tab value="Include file">
        1. Add your site ID to `_config.yml`. `rybbit_instance_url` is only needed if you self-host:

           ```yaml title="_config.yml"
           rybbit_site_id: "YOUR_SITE_ID"
           rybbit_instance_url: "https://app.rybbit.io"
           ```

        2. Create `_includes/rybbit-analytics.html` (create the `_includes/` directory if it does not exist):

           ```html title="_includes/rybbit-analytics.html"
           {% if jekyll.environment == "production" and site.rybbit_site_id %}
             <script src="{{ site.rybbit_instance_url | default: 'https://app.rybbit.io' }}/api/script.js?siteId={{ site.rybbit_site_id }}" defer></script>
           {% endif %}
           ```

           The `jekyll.environment` check keeps the script out of local `jekyll serve` builds; the `site.rybbit_site_id` check keeps it out of builds with no ID configured.

        3. Include it from your layout's `<head>`:

           ```html title="_layouts/default.html"
           <head>
             ...
             {% include rybbit-analytics.html %}
           </head>
           ```
      </Tab>

      <Tab value="Layout file">
        Open `_layouts/default.html` and paste the snippet inside `<head>`, wrapped in a production check so local `jekyll serve` builds are not tracked:

        ```html title="_layouts/default.html"
        <head>
          ...
          {% if jekyll.environment == "production" %}
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>
    </Tabs>

    Build for production and deploy the generated `_site/` directory:

    ```bash
    JEKYLL_ENV=production jekyll build
    ```

    GitHub Pages sets `jekyll.environment` to `production` during its own build, so no extra configuration is needed there.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `jekyll serve` and a plain `jekyll build` run with `jekyll.environment` set to `development`, so the production guard removes the tag. Build with `JEKYLL_ENV=production` and check that output.
* **Config changes not applied**: Jekyll reads `_config.yml` once at startup, so restart `jekyll serve` after adding `rybbit_site_id`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Joomla (/de/docs/guides/joomla)





Joomla has no built-in head-code setting, so the snippet goes in either a **Custom** module assigned to every page or in your template's `index.php`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Joomla [#add-the-snippet-to-joomla]

    <Tabs items="[&#x22;Custom module&#x22;, &#x22;Template file&#x22;]">
      <Tab>
        No file edits are needed, and the module survives template updates.

        1. In the Administrator panel go to **Content → Site Modules** (**Extensions → Modules** on Joomla 3), click **New** and choose **Custom**.

        2. Set **Title** to `Rybbit`, **Show Title** to **Hide**, and **Position** to any position your template renders on every page. Templates rarely expose a `<head>` position; the loader below moves the script into the head from wherever the module is rendered.

        3. In the editor, use the **Toggle Editor** button (or **Code** view) so the script is not stripped, then paste:

           ```html
           <script>
           (function () {
             var s = document.createElement("script");
             s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
             s.defer = true;
             document.head.appendChild(s);
           })();
           </script>
           ```

        4. Set **Status** to **Published**, choose **On all pages** under **Menu Assignment**, and click **Save & Close**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Edit a child template (Joomla 4.1+) or your own copy of the template, otherwise the change is lost on the next template update.
        </Callout>

        1. Go to **System → Site Templates** and open your active template.

        2. Open `index.php` and add the snippet just before `</head>`:

           ```php
           <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
           </head>
           ```

        3. Click **Save & Close**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Module not on the page**: confirm it is published, assigned to **On all pages**, and that the chosen position exists in your template. Then clear the cache under **System → Clear Cache**.
* **TinyMCE strips the script**: open the **Editor - TinyMCE** plugin under **System → Plugins** (**Extensions → Plugins** on Joomla 3) and add `script[src|defer]` to **Extended Valid Elements**, or keep using the toggled-off editor when saving the module.
* **Page caching**: the **System - Page Cache** plugin serves cached HTML, so clear the cache after adding the snippet. The script itself loads client-side and works with cached pages.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Kajabi (/de/docs/guides/kajabi)





Kajabi has a site-wide **Header Page Scripts** field under **Site details** that puts code in the `<head>` of every page, but it deliberately skips Offer checkout and upsell pages. Those have their own **Checkout Tracking Code** setting, so a full install is two pastes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Kajabi [#add-the-snippet-to-kajabi]

    **Site-wide pages**

    1. From the **Dashboard**, open **Settings**.
    2. Under **Site settings**, click **Site details**.
    3. Scroll to **Page scripts** and paste the snippet into **Header Page Scripts**.
    4. Save.

    **Checkout and upsell pages**

    1. From the **Dashboard**, open **Settings**.
    2. Under **Payment settings**, click **Checkout**.
    3. In the **Checkout Tracking Code** section, click to edit the **Header tracking code** and paste the same snippet.
    4. Save.

    <Callout type="info">
      Do not paste the snippet into a page's **Custom Code** section (under **Customize > Settings**). That field is for CSS and JavaScript without `<style>` or `<script>` tags, and it only applies to that one page.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Checkout pages missing from the dashboard**: Header Page Scripts do not run on Offer checkout or upsell pages. Add the snippet under **Settings > Checkout > Checkout Tracking Code** as well.
* **Both fields filled, one visitor, two sites?** Use the same site ID in both places so a visitor who browses your site and then buys is one session, and funnels can follow them through checkout.
* **Snippet added to a page's Custom Code block instead**: the **Add block > Custom Code** block does accept `<script>` tags, but it only covers that page. Keep the site-wide field as the source of truth.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Kirby (/de/docs/guides/kirby)





Kirby templates are plain PHP files in `site/templates/`, and shared markup lives in `site/snippets/`. The snippet goes into whichever file owns your `<head>`: the Starterkit's `site/snippets/header.php`, or the template itself in a Plainkit project.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Kirby [#add-the-snippet-to-kirby]

    <Tabs items="[&#x22;Starterkit&#x22;, &#x22;Plainkit&#x22;]">
      <Tab>
        The Starterkit renders the document head from a shared snippet that every template includes with `<?php snippet('header') ?>`.

        1. Open `site/snippets/header.php`.
        2. Add the tag before `</head>`:

        ```php title="site/snippets/header.php"
        <head>
          <meta charset="utf-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title><?= $site->title() ?> | <?= $page->title() ?></title>
          <?= css(['assets/css/index.css', '@auto']) ?>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        3. Save. Every template that calls `snippet('header')` now loads the script.
      </Tab>

      <Tab>
        The Plainkit's `site/templates/default.php` contains only `<h1><?= $page->title() ?></h1>` and no document structure, so add the tag wherever you build your `<head>`. The usual pattern is a header snippet included by each template:

        ```php title="site/snippets/header.php"
        <!DOCTYPE html>
        <html lang="en">
        <head>
          <meta charset="utf-8">
          <title><?= $page->title() ?></title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        <body>
        ```

        ```php title="site/templates/default.php"
        <?php snippet('header') ?>
        <h1><?= $page->title() ?></h1>
        <?php snippet('footer') ?>
        ```
      </Tab>
    </Tabs>

    To keep the site ID out of the snippet, add it to `site/config/config.php` and read it with `<?= option('rybbit.siteId') ?>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Page cache**: if `cache.pages.active` is enabled in `site/config/config.php`, flush `site/cache/` after editing the snippet or cached pages keep the old head.
* **Multiple header snippets**: templates that include a different header (for example `snippet('header-landing')`) need the tag added there too.
* **Panel is not tracked**: `/panel` is a separate app that does not render your templates, so editing time never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Laravel (/de/docs/guides/laravel)





Laravel renders pages through Blade layouts, so the snippet goes into the layout file that wraps your site. Read the site ID from `config/services.php` and `.env` so it stays out of the template and differs per environment.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Laravel [#add-the-snippet-to-laravel]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to `.env`:

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then register them in `config/services.php`:

    ```php filename="config/services.php"
    <?php

    return [
        // ... other services

        'rybbit' => [
            'instance_url' => env('RYBBIT_INSTANCE_URL', 'https://app.rybbit.io'),
            'site_id' => env('RYBBIT_SITE_ID'),
        ],
    ];
    ```

    Run `php artisan config:clear` if your configuration is cached, otherwise the new keys are not picked up.

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open the Blade layout that wraps your pages. In a default install this is `resources/views/layouts/app.blade.php`; Breeze and Jetstream also ship `resources/views/layouts/guest.blade.php`, and Inertia apps use `resources/views/app.blade.php`. Add the tag inside `<head>`:

    ```php filename="resources/views/layouts/app.blade.php"
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>{{ config('app.name', 'Laravel') }}</title>
        @vite(['resources/css/app.css', 'resources/js/app.js'])

        @production
            <script src="{{ config('services.rybbit.instance_url') }}/api/script.js?siteId={{ config('services.rybbit.site_id') }}" defer></script>
        @endproduction
    </head>
    ```

    `@production` only renders the tag when `APP_ENV=production`, so local development is not tracked. Drop the directive if you also want data from staging.

    If you have several layouts (for example `app` and `guest`), add the tag to each one, or move it into a partial such as `resources/views/partials/rybbit.blade.php` and `@include` it from every layout.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in production**: run `php artisan config:clear` and `php artisan view:clear` after changing `.env` or `config/services.php`; cached config and compiled views keep the old values.
* **Tag missing locally**: `@production` hides it unless `APP_ENV=production`. Set that temporarily to test, or remove the directive.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Leadpages (/de/docs/guides/leadpages)





Every Leadpages page, site and pop-up has an **Analytics** tab in its builder settings with a **Head Section Tracking Code** field, and that is where the snippet goes. In the site builder the setting is site-wide, so one paste covers every page of the site; landing pages built on their own are tracked one page at a time.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Leadpages [#add-the-snippet-to-leadpages]

    1. Open the site or landing page in the builder.
    2. Click the **Settings** gear in the left-hand sidebar, then the **Analytics** tab.
    3. Paste the snippet into **Head Section Tracking Code**.
    4. Click **Save**, then **Update** to push the change to the published page.

    Repeat for each standalone landing page you want tracked. For sites, the code applies to every page in the site.

    Pop-ups have the same tracking code fields in their settings, but a pop-up shown on a page that already carries the snippet does not need its own copy.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: the page was saved but not updated. Click **Update** in the builder to republish.
* **Standalone pages missing**: tracking code on a site does not extend to landing pages published outside that site. Add the snippet to each one.
* **GA4 Measurement ID field**: the Analytics tab also has a field for a Google Analytics ID. That field is for GA4 only; the Rybbit snippet belongs in Head Section Tracking Code.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Lovable (/de/docs/guides/lovable)





Lovable has no project setting for custom head code, so the snippet goes into the app's HTML head like any other code change: ask Lovable to add it in chat, or open the **Code** tab and edit the file yourself. Either way, the live app only picks it up after you publish the change.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Lovable [#add-the-snippet-to-lovable]

    <Tabs items="[&#x22;Ask Lovable&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of the app on every page. Do not remove any existing head tags.
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Check the diff Lovable shows: the tag belongs in the document head, not in a React component.
      </Tab>

      <Tab>
        Open the **Code** tab in the project toolbar (editing needs a paid plan; on the Free plan the editor is read-only). Which file holds the head depends on when the project was created:

        * **Projects created from May 13, 2026** use TanStack Start. Add the script to the `head()` of the root route in `src/routes/__root.tsx`; the `<HeadContent />` component already in that file renders it into the `<head>`:

        ```tsx title="src/routes/__root.tsx"
        export const Route = createRootRoute({
          head: () => ({
            scripts: [
              { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: true },
            ],
          }),
          component: RootComponent,
        });
        ```

        * **Older React + Vite projects** have a single `index.html` at the project root. Paste the snippet before `</head>`:

        ```html title="index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Save with **Cmd+S** / **Ctrl+S**.
      </Tab>
    </Tabs>

    Then click **Publish** in the top right and choose **Publish changes**. Client-side route changes inside the app are tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live app still has no script**: Lovable does not push edits to the published app automatically. A dot on the **Publish** button means unpublished changes; open it and click **Publish changes**.
* **Free plan**: the Code tab is read-only, so use the chat prompt instead.
* **Script disappeared after a later prompt**: Lovable can rewrite the head when it regenerates the layout or upgrades the template. Add "keep the Rybbit script tag" to the project's Knowledge so future edits preserve it, and re-check the page source after big changes.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Magento (/de/docs/guides/magento)





Magento Open Source and Adobe Commerce have a **Scripts and Style Sheets** field in the design configuration that prints HTML into the `<head>` of every storefront page, so no theme edits are needed. On 2.4.7 and later the checkout page runs under a strict Content Security Policy, so the tracker's host also needs a CSP whitelist entry before it loads there.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Magento [#add-the-snippet-to-magento]

    1. In the Admin sidebar, go to **Content > Design > Configuration**.
    2. Find the row for the scope you want to track (usually the store view) and click **Edit** in the **Action** column.
    3. Expand **HTML Head**.
    4. Paste the snippet at the end of **Scripts and Style Sheets** and click **Save Configuration**.
    5. Go to **System > Cache Management** and refresh the invalidated cache types, then purge Varnish or your CDN if you use one.

    #### Allow the tracker under CSP (2.4.7 and later) [#allow-the-tracker-under-csp-247-and-later]

    Magento 2.4.7 switched the checkout page (`checkout_index_index`) to CSP restrict mode; other storefront pages stay in report-only mode. Scripts from hosts that are not whitelisted are blocked on checkout, so add the tracker's host to `script-src` and `connect-src` with a `csp_whitelist.xml` in a module of your own (plus the usual `registration.php` and `etc/module.xml`):

    ```xml title="app/code/Vendor/Rybbit/etc/csp_whitelist.xml"
    <?xml version="1.0"?>
    <csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
        <policies>
            <policy id="script-src">
                <values>
                    <value id="rybbit" type="host">https://app.rybbit.io</value>
                </values>
            </policy>
            <policy id="connect-src">
                <values>
                    <value id="rybbit" type="host">https://app.rybbit.io</value>
                </values>
            </policy>
        </policies>
    </csp_whitelist>
    ```

    Run `bin/magento setup:upgrade` and flush the cache after adding the module. If you self-host Rybbit, whitelist your own instance's domain instead.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

The order success page renders `Magento_Checkout::success.phtml` through the `checkout.success` block, which reserves an `order.success.additional.info` container for extra content. Add a block to that container from the same module as the CSP whitelist; the block reads the order from the checkout session.

```php title="app/code/Vendor/Rybbit/Block/Purchase.php"
<?php
namespace Vendor\Rybbit\Block;

class Purchase extends \Magento\Checkout\Block\Onepage\Success
{
    public function getOrder(): \Magento\Sales\Model\Order
    {
        return $this->_checkoutSession->getLastRealOrder();
    }
}
```

```xml title="app/code/Vendor/Rybbit/view/frontend/layout/checkout_onepage_success.xml"
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="order.success.additional.info">
            <block class="Vendor\Rybbit\Block\Purchase" name="rybbit.purchase" template="Vendor_Rybbit::purchase.phtml" cacheable="false"/>
        </referenceContainer>
    </body>
</page>
```

```php title="app/code/Vendor/Rybbit/view/frontend/templates/purchase.phtml"
<?php
/** @var \Vendor\Rybbit\Block\Purchase $block */
$order = $block->getOrder();
if (!$order->getId()) {
    return;
}
$items = [];
foreach ($order->getAllVisibleItems() as $item) {
    $items[] = [
        'item_id'   => $item->getSku(),
        'item_name' => $item->getName(),
        'price'     => (float) $item->getPrice(),
        'quantity'  => (int) $item->getQtyOrdered(),
    ];
}
$purchase = [
    'transaction_id' => $order->getIncrementId(),
    'value'          => (float) $order->getGrandTotal(),
    'currency'       => $order->getOrderCurrencyCode(),
    'items'          => $items,
];
?>
<script>
document.addEventListener('DOMContentLoaded', function () {
    window.rybbit.event('purchase', <?= /* @noEscape */ json_encode($purchase) ?>);
});
</script>
```

The script waits for `DOMContentLoaded` because the tracker loads with `defer`. Event properties are limited to 2048 characters of JSON, so drop `items` for stores with large orders. `getTaxAmount()` and `getShippingAmount()` are available on the same order object if you want those too.

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: design configuration is scoped, and a store-view row overrides the website and global rows. Edit the row that applies to the storefront you are checking, then flush the page cache and Varnish.
* **Tracked everywhere except checkout**: CSP restrict mode on `checkout_index_index` is blocking the script. Confirm the whitelist module is enabled and look for `Content-Security-Policy` errors naming `app.rybbit.io` in the browser console.
* **Purchase event missing**: `getLastRealOrder()` is only set in the session that placed the order, so reopening the success page later renders nothing.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Mintlify (/de/docs/guides/mintlify)





Mintlify includes every `.js` file in your docs content directory on every page, so the snippet goes into a small JavaScript file that injects the tag.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Mintlify [#add-the-snippet-to-mintlify]

    Create a JavaScript file in your content directory, next to `docs.json` and your `.mdx` pages:

    ```javascript filename="rybbit.js"
    (function () {
      var el = document.createElement("script");
      el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
      el.defer = true;
      document.head.appendChild(el);
    })();
    ```

    Commit and deploy. Mintlify picks the file up automatically; there is nothing to register in `docs.json`. See Mintlify's [custom scripts](https://www.mintlify.com/docs/customize/custom-scripts) page for the current rules on file placement.

    To pass [script attributes](/docs/script#script-attributes) such as skip patterns, set them on the element before appending it:

    ```javascript filename="rybbit.js"
    el.setAttribute("data-skip-patterns", JSON.stringify(["/internal/**"]));
    ```

    <Callout type="info">
      Mintlify sites are single-page apps. Rybbit records client-side navigation as pageviews, so no extra code is needed.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Mintlify pages are MDX, so you can attach handlers inline:

```mdx
<button
  onClick={() => window.rybbit?.event("download_clicked", { file: "getting-started.pdf" })}
>
  Download guide
</button>
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# MkDocs (/de/docs/guides/mkdocs)





MkDocs has an `extra_javascript` setting in `mkdocs.yml` that adds a script tag to every page, which works with any theme. If you run Material for MkDocs you can instead extend the theme and place the tag in `<head>` yourself.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to MkDocs [#add-the-snippet-to-mkdocs]

    <Tabs items="[&#x22;mkdocs.yml&#x22;, &#x22;Material theme override&#x22;]">
      <Tab value="mkdocs.yml">
        Add the script URL to `extra_javascript`. MkDocs 1.5 and later accept the mapping form with a `defer` key:

        ```yaml title="mkdocs.yml"
        extra_javascript:
          - path: https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
            defer: true
        ```

        On MkDocs 1.4 or older, list the plain URL instead:

        ```yaml title="mkdocs.yml"
        extra_javascript:
          - https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
        ```

        Themes render `extra_javascript` entries at the end of `<body>` rather than in `<head>`; the script still loads on every page.
      </Tab>

      <Tab value="Material theme override">
        1. Point Material at an overrides directory in `mkdocs.yml`:

           ```yaml title="mkdocs.yml"
           theme:
             name: material
             custom_dir: overrides
           ```

        2. Create `overrides/main.html` and fill the `extrahead` block, which Material reserves for custom tags inside `<head>`:

           ```html title="overrides/main.html"
           {% extends "base.html" %}

           {% block extrahead %}
             <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
           {% endblock %}
           ```
      </Tab>
    </Tabs>

    Rebuild with `mkdocs build` and deploy the `site/` directory (or `mkdocs gh-deploy`).

    If Material's `navigation.instant` feature is on, page changes go through the History API and Rybbit records them as pageviews without extra code.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Config error on `defer`**: the `path` / `defer` mapping needs MkDocs 1.5+. Run `mkdocs --version` and either upgrade or use the plain URL form.
* **`main.html` has no effect**: the override only applies when `theme.custom_dir` is set and the file sits at `overrides/main.html`, relative to `mkdocs.yml`.
* **Local previews are tracked**: `mkdocs serve` renders the same config as `mkdocs build`. Use a second Rybbit site for local work if that matters.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Moodle (/de/docs/guides/moodle)





Moodle has an **Additional HTML** admin setting that adds code to every page without touching the theme. Its **Within HEAD** field is where the snippet goes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Moodle [#add-the-snippet-to-moodle]

    1. Log in as an administrator and go to **Site administration → Appearance → Additional HTML**.
    2. Paste the snippet into **Within HEAD**.
    3. Click **Save changes**.

    The snippet now loads on every page, including course pages, activities and the login page. Users must be able to reach `app.rybbit.io` from their browser; nothing is proxied through the Moodle server.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Moodle renders standard HTML, so `data-rybbit-event` attributes work anywhere you control markup, for example in a course page's HTML block or a label:

```html
<a href="/course/view.php?id=42" data-rybbit-event="course_open" data-rybbit-prop-course="42">
  Open course
</a>
```

For enrolment or completion events, call `window.rybbit.event()` from a small block of JavaScript placed in the **When BODY is closed** field of the same Additional HTML page.

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the page source**: Moodle caches rendered output. Go to **Site administration → Development → Purge caches** and reload.
* **Pages inside the mobile app are not tracked**: the Moodle app renders course content in its own WebView with its own pages; the Additional HTML setting only affects the web site.
* **Snippet pasted into Custom CSS**: theme settings such as Boost's **Raw SCSS** only accept styles. Use Additional HTML for script tags.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Nextra (/de/docs/guides/nextra)





Nextra is a Next.js docs framework, so the snippet goes where it goes in any Next.js app: the root layout, rendered with `next/script`. Nextra 4 uses the App Router and `app/layout.jsx`; Nextra 3 uses the Pages Router and `pages/_app.jsx`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Nextra [#add-the-snippet-to-nextra]

    Use the `Script` component with `strategy="afterInteractive"` rather than a plain `<script>` tag; the `defer` attribute from the snippet is not needed.

    <Tabs items="[&#x22;Nextra 4 (App Router)&#x22;, &#x22;Nextra 3 (Pages Router)&#x22;]">
      <Tab value="Nextra 4 (App Router)">
        Add the `Script` next to the `Layout` in `app/layout.jsx` (or `.tsx`):

        ```jsx title="app/layout.jsx"
        import { Footer, Layout, Navbar } from "nextra-theme-docs";
        import { Head } from "nextra/components";
        import { getPageMap } from "nextra/page-map";
        import Script from "next/script";
        import "nextra-theme-docs/style.css";

        export default async function RootLayout({ children }) {
          return (
            <html lang="en" dir="ltr" suppressHydrationWarning>
              <Head />
              <body>
                <Layout
                  navbar={<Navbar logo={<b>My Docs</b>} />}
                  pageMap={await getPageMap()}
                  footer={<Footer>MIT {new Date().getFullYear()} © My Docs.</Footer>}
                >
                  {children}
                </Layout>
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```
      </Tab>

      <Tab value="Nextra 3 (Pages Router)">
        Create `pages/_app.jsx` if your project does not have one, and render the `Script` beside the page:

        ```jsx title="pages/_app.jsx"
        import Script from "next/script";

        export default function App({ Component, pageProps }) {
          return (
            <>
              <Component {...pageProps} />
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </>
          );
        }
        ```

        Do not put the tag in the `head` option of `theme.config.jsx`: that option renders through `next/head`, and Next.js warns against loading scripts there.
      </Tab>
    </Tabs>

    Nextra navigates between pages client-side. Rybbit records those route changes as pageviews, so no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Only the docs pages are tracked**: in Nextra 4 the tag belongs in the root `app/layout.jsx`, not in a nested `app/docs/layout.jsx`, otherwise landing pages outside `docs/` are missed.
* **Upgrading from Nextra 3**: Nextra 4 dropped the Pages Router and `theme.config`. Move the `Script` from `pages/_app.jsx` to `app/layout.jsx` as part of the migration.
* **Proxying through your own domain**: see the [Next.js guide](/docs/guides/react/next-js) for rewrites; every endpoint must be rewritten, not just `script.js`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Odoo (/de/docs/guides/odoo)





The Odoo Website app has a **Code Injection** setting in the website editor's theme panel with separate `<head>` and `</body>` fields that apply to every page of the website. The snippet goes in the `<head>` field. This works on Odoo Online, Odoo.sh and on-premise installs of Odoo 17 and 18.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Odoo [#add-the-snippet-to-odoo]

    1. Open your website's frontend and click **Edit** in the top bar.
    2. Switch to the **Theme** tab of the editor panel.
    3. Scroll to the **Advanced** section and, next to **Code Injection*&#x2A;, click &#x2A;*`<head>`**.
    4. Paste the snippet into the editor that opens and click **Save**.
    5. Click **Save** in the website editor to publish the change.

    The code is stored per website. If you run several websites from one Odoo database, switch website in the top bar and repeat the steps for each one.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Odoo eCommerce pages render standard HTML, so use `data-rybbit-event` attributes on any element you add in the editor, or call `window.rybbit.event()` from the `</body>` Code Injection field:

```html
<script>
  document.addEventListener("click", function (e) {
    if (e.target.closest("#add_to_cart")) {
      window.rybbit.event("add_to_cart");
    }
  });
</script>
```

The confirmation page is served at `/shop/confirmation`; a script that checks `window.location.pathname` there can send a `purchase` event once per order.

## Troubleshooting [#troubleshooting]

* **The `<head>` button is missing**: Code Injection requires the **Website → Editor and Designer** access right. An administrator can grant it under **Settings → Users & Companies → Users**, on the user's **Access Rights** tab.
* **Change is visible while logged in but not for visitors**: click **Save** in the editor after closing the code window; the code is published with the page.
* **Multiple websites**: the field applies only to the website currently selected in the editor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Payload (/de/docs/guides/payload)





Payload is a headless CMS that installs into a Next.js app: the admin panel lives in the `(payload)` route group and your site in the `(frontend)` route group. The tracking snippet goes into the frontend root layout, not into Payload's config or admin panel.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Payload [#add-the-snippet-to-payload]

    <Callout type="info">
      Payload has no template or head setting to paste into. Add the snippet to the root layout of the Next.js frontend that renders your site.
    </Callout>

    In both the `website` and `blank` templates created by `npx create-payload-app`, the frontend root layout is `src/app/(frontend)/layout.tsx`. Render `next/script` there, exactly as in the [Next.js guide](/docs/guides/react/next-js), so the script loads on every public route and stays out of the admin panel under `src/app/(payload)/`.

    ```tsx title="src/app/(frontend)/layout.tsx"
    import Script from "next/script";

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            {children}
            <Script
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    The script tracks client-side route changes automatically, so Next.js `<Link>` navigation between Payload pages and posts is counted without extra code.

    If your frontend is a separate app (Nuxt, Astro, SvelteKit) that fetches from Payload's REST or GraphQL API, follow that framework's guide instead: [Nuxt](/docs/guides/vue/nuxt), [Astro](/docs/guides/astro), [SvelteKit](/docs/guides/svelte/sveltekit), [Remix](/docs/guides/react/remix).
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live Preview counts as visits**: the admin panel's Live Preview loads your frontend in an iframe at the URL set in `admin.livePreview.url`. Editors' preview sessions are tracked like any other visitor. Point `livePreview.url` at a separate preview deployment registered as its own site in Rybbit, or skip the tag in preview builds.
* **Draft preview routes**: if you use the `website` template's `/next/preview` route or Next.js draft mode, those pages are also tracked. Add `data-skip-patterns='["/next/**"]'` to the script tag to exclude them.
* **Admin panel is not tracked**: `/admin` is rendered by the `(payload)` route group, which has its own layout without the snippet. Put the tag in the `(frontend)` layout only.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Phoenix (/de/docs/guides/phoenix)





Phoenix renders every page inside the root layout, `lib/my_app_web/components/layouts/root.html.heex`, which owns the `<html>` and `<head>` tags, so the snippet goes there. Read the site ID from application config set in `config/runtime.exs`, so it comes from an environment variable at boot and stays out of the template.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Phoenix [#add-the-snippet-to-phoenix]

    #### Configure the site ID [#configure-the-site-id]

    `config/runtime.exs` runs when the app boots, including inside a release, so it is the right place to read environment variables. Add a `:rybbit` key for your app (replace `:my_app` with your OTP app name):

    ```elixir filename="config/runtime.exs"
    config :my_app, :rybbit,
      instance_url: System.get_env("RYBBIT_INSTANCE_URL", "https://app.rybbit.io"),
      site_id: System.get_env("RYBBIT_SITE_ID")
    ```

    Then set the variables where the app runs:

    ```bash
    export RYBBIT_INSTANCE_URL=https://app.rybbit.io
    export RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    #### Expose the config to the layout [#expose-the-config-to-the-layout]

    Templates in `lib/my_app_web/components/layouts/` are embedded into the `MyAppWeb.Layouts` module, so a function defined there is callable from `root.html.heex`. Add one that returns the config:

    ```elixir filename="lib/my_app_web/components/layouts.ex"
    defmodule MyAppWeb.Layouts do
      use MyAppWeb, :html

      embed_templates "layouts/*"

      def rybbit_config, do: Application.get_env(:my_app, :rybbit, [])
    end
    ```

    #### Add the tag to the root layout [#add-the-tag-to-the-root-layout]

    Open `lib/my_app_web/components/layouts/root.html.heex` and add the tag inside `<head>`, after the existing `app.css` and `app.js` tags:

    ```html filename="lib/my_app_web/components/layouts/root.html.heex"
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta name="csrf-token" content={get_csrf_token()} />
      <.live_title suffix=" · Phoenix Framework">{assigns[:page_title] || "MyApp"}</.live_title>
      <link phx-track-static rel="stylesheet" href={~p"/assets/app.css"} />
      <script defer phx-track-static type="text/javascript" src={~p"/assets/app.js"}></script>

      <script
        :if={rybbit_config()[:site_id]}
        src={"#{rybbit_config()[:instance_url]}/api/script.js?siteId=#{rybbit_config()[:site_id]}"}
        defer
      ></script>
    </head>
    ```

    The `:if` attribute skips the tag when `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.

    #### LiveView navigation [#liveview-navigation]

    `<.link navigate>`, `<.link patch>`, `push_navigate/2` and `push_patch/2` change the URL with `history.pushState` (or `replaceState` when `replace: true`) and keep the root layout, including its `<head>`, in place. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each live navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `phx:` event listener is needed. A regular `<.link href>` does a full page load, which the script also tracks.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `config/runtime.exs` is evaluated at boot, so restart the app or release after changing `RYBBIT_SITE_ID`. Check with `Application.get_env(:my_app, :rybbit)` in `iex -S mix`.
* **Content Security Policy**: if you set a `content-security-policy` header in a plug, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Podia (/de/docs/guides/podia)





Podia has a **Third-party code** setting under **Settings > Analytics** that adds the snippet to every public page of your site, including checkout. Podia inserts custom code just before the closing `</body>` tag rather than in `<head>`; the Rybbit script loads with `defer` and works the same from either position.

<Callout type="warn">
  Third-party code is available on Podia's **Mover** and **Shaker** plans. On the free plan the Third-party code option is not shown.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Podia [#add-the-snippet-to-podia]

    1. From your home feed, click your site name and choose **Admin**.
    2. In the Admin sidebar, open **Settings > Analytics**.
    3. Click **Edit** next to **Third-party code**.
    4. Paste the snippet into the **Website tracking code** field.
    5. Click **Save**. The code is live as soon as it is saved; there is no separate publish step.

    The website tracking code runs on every public page of your site and on checkout pages. It does not run inside logged-in areas such as the customer dashboard, product viewer or community spaces.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Podia has a second field, **Conversion tracking code**, directly below the website tracking code. Code in that field runs only on the thank-you page after a purchase or membership signup, and Podia exposes the order as a `Podia.Conversion` object on that page (once per order; it is gone after a refresh).

Paste this into **Conversion tracking code** to send a `purchase` event with the order details:

```html
<script>
(function () {
  var c = window.Podia && window.Podia.Conversion;
  if (!c) return;
  var payload = {
    product: c.object.name,
    order_id: c.object.order_id,
    value: c.revenue,
    currency: c.currency
  };
  var start = Date.now();
  (function send() {
    if (window.rybbit && typeof window.rybbit.event === "function") {
      return window.rybbit.event("purchase", payload);
    }
    if (Date.now() - start < 8000) setTimeout(send, 150);
  })();
})();
</script>
```

The short polling loop is there because Podia runs the conversion code before the deferred tracking script has finished loading. `revenue` is `0` for free products and free membership plans, so filter on `value` in the dashboard if you only want paid orders.

## Troubleshooting [#troubleshooting]

* **No Third-party code option**: the site is on the free plan. Third-party code requires Mover or Shaker.
* **No pageviews while you test**: Podia does not output tracking code when you are logged in to your own Podia account. Test in a private window, or log out first.
* **Logged-in member pages are missing**: expected. Custom code runs only on public pages and checkout, not in the customer dashboard, product viewer or community.
* **Duplicate purchase events**: `Podia.Conversion` is only present on the first load of the thank-you page, so a refresh does not resend. If you see duplicates, make sure the event script is in Conversion tracking code only and not also in Website tracking code.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Preact (/de/docs/guides/preact)





A Preact app scaffolded with `npm init preact` (or Vite's `preact` template) has a single `index.html` at the project root. Paste the snippet into its `<head>` and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Preact [#add-the-snippet-to-preact]

    Open `index.html` at the root of the project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Vite + Preact</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/index.jsx"></script>
      </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Route changes made by `preact-iso`, `preact-router` or a similar router are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw.

```jsx title="src/components/SignupButton.jsx"
export function SignupButton() {
  const handleClick = () => {
    if (window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# PrestaShop (/de/docs/guides/prestashop)





PrestaShop's back office has no built-in setting for custom `<head>` code, so the snippet goes in either through a header-injection module from the Addons marketplace or directly into your theme's `head.tpl`. Either way, clear the cache afterwards.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to PrestaShop [#add-the-snippet-to-prestashop]

    <Tabs items="[&#x22;Custom code module&#x22;, &#x22;Theme files&#x22;]">
      <Tab>
        1. In the back office, go to **Modules > Module Manager** (or **Module Catalog**) and install a module that injects custom HTML into the page header, for example a "Custom HTML" or "Header code" module from the [PrestaShop Addons marketplace](https://addons.prestashop.com/).
        2. Open the module's configuration, paste the snippet into its head / header code field, and save.
        3. Go to **Advanced Parameters > Performance** and click **Clear cache**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Edit a child theme. Changes to the parent theme are lost on theme updates.
        </Callout>

        1. Over FTP/SFTP or a file manager, open `/themes/your-theme-name/templates/_partials/head.tpl`.
        2. Paste the snippet at the end of the file, before the closing `</head>` tag, and save.
        3. Go to **Advanced Parameters > Performance** and click **Clear cache**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Add this to your theme's `order-confirmation.tpl`, or output it from a module hooked to the order confirmation page. PrestaShop renders templates with Smarty, so the `$order` variables are filled in with the order data:

```html
{if isset($order)}
<script>
(function () {
  function waitForRybbit(callback, timeout) {
    var start = Date.now();
    (function check() {
      if (window.rybbit && typeof window.rybbit.event === 'function') {
        callback();
      } else if (Date.now() - start < timeout) {
        setTimeout(check, 100);
      }
    })();
  }

  waitForRybbit(function () {
    window.rybbit.event('purchase', {
      transaction_id: '{$order.details.reference}',
      value: {$order.totals.total.amount},
      currency: '{$order.totals.total.currency}'
    });
  }, 5000);
})();
</script>
{/if}
```

`waitForRybbit` polls until the tracking script from `head.tpl` has defined `window.rybbit`, so the event is not lost when the confirmation script runs first.

## Troubleshooting [#troubleshooting]

* **Script not on the page**: clear the cache under **Advanced Parameters > Performance**, and temporarily disable any JavaScript optimisation or combine/minify module.
* **Theme updates overwrite the snippet**: keep template edits in a child theme; parent-theme changes are lost on update.
* **Purchase event missing**: the `$order` Smarty variables differ between PrestaShop versions. Compare them with your version's `order-confirmation.tpl` and place a test order to confirm the event arrives.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Qwik (/de/docs/guides/qwik)





A Qwik City app renders the whole document from `src/root.tsx`, which owns the `<head>` and `<body>` elements. Add the snippet to that `<head>` and it is on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Qwik [#add-the-snippet-to-qwik]

    Open `src/root.tsx` and add the tag inside `<head>`, after `<RouterHead />`:

    ```tsx title="src/root.tsx"
    import { component$ } from "@builder.io/qwik";
    import { QwikCityProvider, RouterOutlet } from "@builder.io/qwik-city";
    import { RouterHead } from "./components/router-head/router-head";

    import "./global.css";

    export default component$(() => {
      return (
        <QwikCityProvider>
          <head>
            <meta charset="utf-8" />
            <RouterHead />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body lang="en">
            <RouterOutlet />
          </body>
        </QwikCityProvider>
      );
    });
    ```

    `src/components/router-head/router-head.tsx` renders per-route `head` exports (title, meta, links). Keep the Rybbit tag in `root.tsx` so it does not depend on any route's `head` export.

    Navigations through Qwik City's `<Link>` component are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a `$` event handler. Handlers only run in the browser, so `window` is always defined; guard against a blocked or still-loading script.

```tsx title="src/components/signup-button.tsx"
import { component$ } from "@builder.io/qwik";

export const SignupButton = component$(() => {
  return (
    <button
      onClick$={() => {
        if (window.rybbit) {
          window.rybbit.event("signup_click", { location: "hero" });
        }
      }}
    >
      Sign up
    </button>
  );
});
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ruby on Rails (/de/docs/guides/rails)





Rails wraps every page in `app/views/layouts/application.html.erb`, so the snippet goes into that layout's `<head>`. Read the site ID from a custom `config.x` setting fed by an environment variable, so the template stays free of hard-coded IDs and each environment can use its own site.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ruby on Rails [#add-the-snippet-to-ruby-on-rails]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to your environment (`.env` if you use dotenv-rails, otherwise your host's environment settings):

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then expose them through the `config.x` namespace in `config/application.rb`:

    ```ruby filename="config/application.rb"
    module MyApp
      class Application < Rails::Application
        # ... existing configuration

        config.x.rybbit.instance_url = ENV.fetch("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
        config.x.rybbit.site_id = ENV["RYBBIT_SITE_ID"]
      end
    end
    ```

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open `app/views/layouts/application.html.erb` and add the tag inside `<head>`, after the stylesheet and JavaScript tags:

    ```erb filename="app/views/layouts/application.html.erb"
    <head>
      <title><%= content_for(:title) || "MyApp" %></title>
      <meta name="viewport" content="width=device-width,initial-scale=1">
      <%= csrf_meta_tags %>
      <%= csp_meta_tag %>
      <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
      <%= javascript_importmap_tags %>

      <% if Rails.configuration.x.rybbit.site_id.present? %>
        <script src="<%= Rails.configuration.x.rybbit.instance_url %>/api/script.js?siteId=<%= Rails.configuration.x.rybbit.site_id %>" defer></script>
      <% end %>
    </head>
    ```

    The `if` guard skips the tag wherever `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.

    If you have more than one HTML layout (for example `application.html.erb` and `admin.html.erb`), add the tag to each, or move it into a partial such as `app/views/layouts/_rybbit.html.erb` and `<%= render "layouts/rybbit" %>` from every layout. Mailer layouts do not need it.

    #### Turbo and Hotwire [#turbo-and-hotwire]

    Turbo Drive replaces the page `<body>` on each visit, merges the `<head>`, and pushes the new URL with `history.pushState`. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so every Turbo visit is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `turbo:load` listener is needed. Because the script tag is in `<head>` and identical on every page, Turbo Drive keeps the existing tag instead of loading it again.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `config/application.rb` is read once at boot, so restart the server after changing `RYBBIT_SITE_ID`. Check `Rails.configuration.x.rybbit.site_id` in `rails console` if the tag does not render.
* **Content Security Policy**: if you set a policy in `config/initializers/content_security_policy.rb`, add your Rybbit host to `script_src` and `connect_src`, or the browser blocks both the script and the `/api/track` requests. Alternatively [proxy the script](/docs/proxy-guide) through your own domain so no extra origin is needed.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Replit (/de/docs/guides/replit)





Replit has no publishing setting for custom head code, so the snippet goes into the app's HTML entry file: ask Agent to add it, or open the file in the workspace and paste it yourself. The change reaches the live URL only after you republish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Replit [#add-the-snippet-to-replit]

    <Tabs items="[&#x22;Ask Agent&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the Agent chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of the app's HTML entry file so it loads on every page. Keep all existing head tags.
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Review the change before you approve it: the tag belongs in the HTML document, not in a React component or server file.
      </Tab>

      <Tab>
        Open the file that owns the `<head>` from the **Files** pane of the workspace:

        * Agent-built web apps are typically a Vite + React client with an Express server, and the HTML entry is `client/index.html`. Some projects keep it at `index.html` in the project root.
        * Next.js projects use `app/layout.tsx` with `next/script`, as in the [Next.js guide](/docs/guides/react/next-js).
        * Plain HTML projects (Static deployments): add the tag to every page, or to the shared template if you have one.

        Paste the snippet before `</head>`:

        ```html title="client/index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```
      </Tab>
    </Tabs>

    Then click **Publish** in the upper right (or **Republish** for an app that is already live) so a new release goes out at the same URL. In-app route changes are tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live app has no script**: changes in the Project Editor do not replace the live release on their own. Test in Preview, then click **Republish**.
* **Agent rewrote the file**: a later request can regenerate `client/index.html`. Tell Agent to keep the Rybbit script when you ask for layout changes, and re-check the page source after large refactors.
* **Numbers differ from Replit's deployment analytics**: Replit counts requests at the server; Rybbit counts browser pageviews after ad blockers and bot filtering, so the two rarely match exactly.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Sanity (/de/docs/guides/sanity)





Sanity is a headless CMS: your frontend queries content from the Content Lake and Sanity Studio is only the editing app. The tracking snippet therefore goes into the frontend that renders your site, not into Sanity.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Sanity [#add-the-snippet-to-sanity]

    <Callout type="info">
      Sanity has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Sanity.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Sanity frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby)
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Embedded Studio pageviews**: if Sanity Studio is mounted inside your frontend (for example at `/studio` in a Next.js app), the snippet in your root layout also runs there. Add `data-skip-patterns='["/studio/**"]'` to the script tag so editor sessions are not counted as visits.
* **Hosted Studio is not tracked**: a Studio deployed to `*.sanity.studio` is a separate app without the snippet, so time spent editing never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Shopify Hydrogen (/de/docs/guides/shopify-hydrogen)





Hydrogen storefronts render the HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file's `Layout` component, and the tracker's host is added to the Content Security Policy that `app/entry.server.tsx` builds. This guide is for headless Hydrogen storefronts; for an Online Store theme, see the [Shopify guide](/docs/guides/shopify).

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Shopify Hydrogen [#add-the-snippet-to-shopify-hydrogen]

    Hydrogen ships with a nonce-based CSP, so a plain `<script>` tag without the nonce is blocked. Use Hydrogen's `Script` component, which adds the nonce for you.

    1. Open `app/root.tsx` and add the tag inside `<head>` of the `Layout` component:

    ```tsx title="app/root.tsx"
    import { Analytics, getShopAnalytics, Script, useNonce } from "@shopify/hydrogen";

    export function Layout({children}: {children?: React.ReactNode}) {
      const nonce = useNonce();

      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width,initial-scale=1" />
            <Meta />
            <Links />
            <Script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer />
          </head>
          <body>
            {children}
            <ScrollRestoration nonce={nonce} />
            <Scripts nonce={nonce} />
          </body>
        </html>
      );
    }
    ```

    2. Open `app/entry.server.tsx` and allow the tracker's host in the CSP. Values you pass for `connectSrc` are merged with Hydrogen's defaults, but `scriptSrc` has no default to merge with (it falls back to `default-src`), so list Shopify's CDN alongside Rybbit:

    ```tsx title="app/entry.server.tsx"
    const {nonce, header, NonceProvider} = createContentSecurityPolicy({
      shop: {
        checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
        storeDomain: context.env.PUBLIC_STORE_DOMAIN,
      },
      scriptSrc: ["'self'", "https://cdn.shopify.com", "https://app.rybbit.io"],
      connectSrc: ["https://app.rybbit.io"],
    });
    ```

    `connect-src` lets the tracker post events; `script-src` is needed because features such as session replay load a second script from the same host at runtime. If you self-host Rybbit, use your instance's domain.

    Restart the dev server. Client-side navigation between routes is tracked automatically as pageviews. Projects created before Hydrogen moved to React Router import `Meta`, `Links` and `Scripts` from `@remix-run/react`; the edit is the same.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Hydrogen's `Analytics.Provider` already publishes storefront events (`product_viewed`, `product_added_to_cart`, `cart_updated` and others), so subscribe to them once in a small component instead of instrumenting each route.

```tsx title="app/components/RybbitAnalytics.tsx"
import { useAnalytics } from "@shopify/hydrogen";
import { useEffect } from "react";

export function RybbitAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register("Rybbit");

  useEffect(() => {
    subscribe("product_viewed", (data) => {
      const product = data.products[0];
      if (!product) return;
      window.rybbit?.event("view_item", {
        item_id: product.sku || product.variantId,
        item_name: product.title,
        item_variant: product.variantTitle,
        price: Number(product.price),
      });
    });
    subscribe("product_added_to_cart", (data) => {
      const line = data.currentLine;
      if (!line) return;
      window.rybbit?.event("add_to_cart", {
        item_id: line.merchandise.sku || line.merchandise.id,
        item_name: line.merchandise.product.title,
        price: Number(line.cost.totalAmount.amount),
        currency: line.cost.totalAmount.currencyCode,
        quantity: line.quantity,
      });
    });
    ready();
  }, []);

  return null;
}
```

Render `<RybbitAnalytics />` inside `<Analytics.Provider>` in the `App` component of `app/root.tsx`. Declare `window.rybbit` with the type from [Track events](/docs/track-events#typescript-support) so TypeScript accepts the calls. Skip `page_viewed`: the tracker records route changes itself.

<Callout type="info">
  Checkout does not run in Hydrogen. Track purchases with the custom web pixel from the [Shopify guide](/docs/guides/shopify#purchase), which works for Hydrogen and Online Store checkouts alike.
</Callout>

## Troubleshooting [#troubleshooting]

* **`Refused to load the script` in the console**: the CSP change in `entry.server.tsx` is missing or the dev server was not restarted. The nonce alone is not enough once session replay loads its second script.
* **`POST /api/track` blocked**: `connectSrc` does not include the tracker's host. Self-hosted instances need their own domain here.
* **Early events dropped**: on a cold load a subscription can fire before the deferred script runs. The optional chaining above skips those; wrap the calls in `window.rybbit.onReady()` if you need every one.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Shopify (/de/docs/guides/shopify)





On Shopify the snippet goes into your theme's `theme.liquid` layout, which wraps every storefront page. Checkout runs on Shopify's own sandboxed pages, so purchases are tracked separately through a custom web pixel.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Shopify [#add-the-snippet-to-shopify]

    1. In Shopify admin, go to **Online Store > Themes**.
    2. On your current theme, click the &#x2A;*...** button next to **Customize** and choose **Edit code**.
    3. Open `theme.liquid` in the **Layout** folder.
    4. Paste the snippet just before the closing `</head>` tag and click **Save**.

    Theme updates can overwrite `theme.liquid`. Shopify has no child-theme system, so after updating a purchased theme, re-add the snippet.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Storefront templates can call `window.rybbit.event()` directly. Wrap the calls in a `DOMContentLoaded` listener because the tracking script is loaded with `defer`, and divide Liquid prices by 100 because they are in cents.

<Callout type="warn">
  Back up your theme before editing code. Liquid object names such as `product.selected_or_first_available_variant` and the form selectors below vary between themes, so adjust them to match yours.
</Callout>

#### View product [#view-product]

Add to your main product template (`sections/main-product.liquid` or `templates/product.liquid`, depending on the theme):

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var variant = {{ product.selected_or_first_available_variant | json }};
  window.rybbit.event('view_item', {
    item_id: variant.sku || variant.id,
    item_name: {{ product.title | json }},
    item_variant: variant.title === 'Default Title' ? null : variant.title,
    price: variant.price / 100,
    currency: {{ cart.currency.iso_code | json }}
  });
});
</script>
```

#### Add to cart [#add-to-cart]

In the same template, listen on the product form. Themes with an AJAX cart drawer usually fire their own JavaScript event after an item is added; hooking that is more reliable than the form submit.

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var form = document.querySelector('form[action="/cart/add"]');
  if (!form) return;
  form.addEventListener('submit', function () {
    var variant = {{ product.selected_or_first_available_variant | json }};
    var qty = form.querySelector('[name="quantity"]');
    window.rybbit.event('add_to_cart', {
      item_id: variant.sku || variant.id,
      item_name: {{ product.title | json }},
      price: variant.price / 100,
      currency: {{ cart.currency.iso_code | json }},
      quantity: qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1
    });
  });
});
</script>
```

#### Begin checkout [#begin-checkout]

Add to your cart template (`sections/main-cart-items.liquid` or `templates/cart.liquid`) to track clicks on the checkout button:

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var button = document.querySelector('[name="checkout"]');
  if (!button) return;
  button.addEventListener('click', function () {
    var cart = {{ cart | json }};
    window.rybbit.event('begin_checkout', {
      currency: cart.currency,
      value: cart.total_price / 100,
      items: cart.items.map(function (item) {
        return { item_id: item.sku || item.variant_id, quantity: item.quantity, price: item.final_price / 100 };
      })
    });
  });
});
</script>
```

Event properties are limited to 2048 characters of serialised JSON and larger payloads are rejected, not truncated. Keep `items` compact, or send only the totals for large carts.

#### Purchase [#purchase]

Checkout and the order status page do not load your theme, and the old **Order status page > Additional scripts** field is deprecated: view-only since August 28, 2025, with non-Plus stores required to migrate by August 26, 2026. Track purchases with a custom web pixel from [Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations) instead.

Pixels run in a sandbox with no access to `window.rybbit`, so the pixel posts the event straight to Rybbit's track endpoint.

1. In Shopify admin, go to **Settings > Customer events**.
2. Click **Add custom pixel**, name it `Rybbit`, and click **Add pixel**.
3. Paste the code below, replace `YOUR_SITE_ID`, then **Save** and **Connect** the pixel.

```javascript
analytics.subscribe("checkout_completed", (event) => {
  const checkout = event.data.checkout;
  const items = (checkout.lineItems || []).map((li) => ({
    id: li.variant?.sku || li.variant?.id,
    qty: li.quantity,
    price: li.variant?.price?.amount,
  }));

  fetch("https://app.rybbit.io/api/track", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    keepalive: true,
    body: JSON.stringify({
      type: "custom_event",
      site_id: "YOUR_SITE_ID",
      event_name: "purchase",
      // properties must be a JSON string of at most 2048 characters
      properties: JSON.stringify({
        transaction_id: checkout.order?.id || checkout.token,
        value: checkout.totalPrice?.amount,
        currency: checkout.currencyCode,
        items,
      }),
    }),
  });
});
```

`checkout_completed` fires once per placed order. The same [Customer Events](https://shopify.dev/docs/api/customer-events) API also exposes `product_added_to_cart` and `checkout_started`, so you can move add-to-cart and begin-checkout into the pixel too if theme code is unreliable on your store.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# SolidJS (/de/docs/guides/solid)





A client-side Solid app built with Vite has a single `index.html` at the project root; a SolidStart app renders its document from `src/entry-server.tsx`. Paste the snippet into the `<head>` of whichever file your project has and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to SolidJS [#add-the-snippet-to-solidjs]

    <Tabs items="[&#x22;Vite&#x22;, &#x22;SolidStart&#x22;]">
      <Tab value="Vite">
        Open `index.html` at the root of the project (the file `npm create solid@latest` generates for the vanilla templates) and paste the snippet inside `<head>`:

        ```html title="index.html"
        <!DOCTYPE html>
        <html lang="en">
          <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <title>Solid App</title>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            <div id="root"></div>
            <script src="/src/index.tsx" type="module"></script>
          </body>
        </html>
        ```
      </Tab>

      <Tab value="SolidStart">
        SolidStart has no `index.html`. The `<html>` document is the `document` prop of `<StartServer>` in `src/entry-server.tsx`; `src/app.tsx` only renders the router inside it. Add the tag to `<head>` next to `{assets}`:

        ```tsx title="src/entry-server.tsx"
        // @refresh reload
        import { createHandler, StartServer } from "@solidjs/start/server";

        export default createHandler(() => (
          <StartServer
            document={({ assets, children, scripts }) => (
              <html lang="en">
                <head>
                  <meta charset="utf-8" />
                  <meta name="viewport" content="width=device-width, initial-scale=1" />
                  <link rel="icon" href="/favicon.ico" />
                  <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
                  {assets}
                </head>
                <body>
                  <div id="app">{children}</div>
                  {scripts}
                </body>
              </html>
            )}
          />
        ));
        ```

        Restart the dev server after the change.
      </Tab>
    </Tabs>

    Route changes made by `@solidjs/router` (including SolidStart's file routes) are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw; in SolidStart the guard also covers server rendering.

```tsx title="src/components/SignupButton.tsx"
export default function SignupButton() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Squarespace (/de/docs/guides/squarespace)





Squarespace injects custom HTML into every page through its **Code Injection** panel, so no template edits are needed.

<Callout type="warn">
  Code Injection is available on the **Business** and **Commerce** plans. It is not available on the Personal plan.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Squarespace [#add-the-snippet-to-squarespace]

    1. From the Home Menu, open **Settings**.
    2. Open **Website**, then **Code Injection** (listed under **Advanced** or **Developer** depending on your Squarespace version).
    3. Paste the snippet into the **Header** field. The script is deferred, so it does not delay page rendering.
    4. Click **Save** at the top of the panel.

    The **Footer** field also works and loads the script on every page. Leave the **Lock Page** and **Order Confirmation Page** fields alone; they only apply to those single pages.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Code Injection is missing from Settings**: the site is on the Personal plan. Upgrade to Business or Commerce.
* **Only the checkout is tracked**: the snippet was pasted into **Order Confirmation Page** instead of **Header** or **Footer**.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Starlight (/de/docs/guides/starlight)





Starlight, the documentation theme for Astro, has a `head` option in its integration config that adds tags to every page. The snippet goes there, in `astro.config.mjs`, so no component overrides are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Starlight [#add-the-snippet-to-starlight]

    Open `astro.config.mjs` at the root of your project and add a `script` entry to the `head` array of the `starlight()` integration:

    ```javascript title="astro.config.mjs"
    import { defineConfig } from "astro/config";
    import starlight from "@astrojs/starlight";

    export default defineConfig({
      integrations: [
        starlight({
          title: "My Docs",
          head: [
            {
              tag: "script",
              attrs: {
                src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                defer: true,
              },
            },
          ],
        }),
      ],
    });
    ```

    Each `head` entry becomes an HTML element with the given attributes; `defer: true` renders as a boolean attribute. Rebuild with `npm run build` and deploy the `dist/` directory.

    <Callout type="info">
      Entries in `head` are written to the page as-is and skip Astro's script bundling, which is what you want for a remote tracker. Only override the `Head` component if you need to import a local asset.
    </Callout>

    Starlight serves each page as a full document, so every navigation is a normal pageview and no route-change handling is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Local previews are tracked**: `head` applies to `astro dev` as well as `astro build`. Read the site ID from an environment variable that only your deploy sets (`process.env.RYBBIT_SITE_ID`) and push the entry only when it is present, or keep a separate site in Rybbit for development.
* **Tag missing after editing the config**: the dev server restarts itself when `astro.config.mjs` changes, but a deployed site needs a fresh build.
* **Head component override**: if your project already overrides Starlight's `Head` component, make sure it still renders the default head (the override docs show how), otherwise config `head` entries are dropped with it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Statamic (/de/docs/guides/statamic)





Statamic wraps every template in a layout, and a fresh install uses `resources/views/layout.antlers.html` by default. The snippet goes in that layout's `<head>`, so it loads on every page without touching individual templates.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Statamic [#add-the-snippet-to-statamic]

    1. Open `resources/views/layout.antlers.html`.
    2. Add the tag before `</head>`:

    ```html title="resources/views/layout.antlers.html"
    <!doctype html>
    <html lang="{{ site:short_locale }}">
    <head>
        <meta charset="utf-8">
        <title>{{ title }} | {{ site:name }}</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        {{ template_content }}
    </body>
    </html>
    ```

    3. Save. Templates rendered through this layout (`{{ template_content }}`) now include the script.

    If an entry or collection sets a different `layout` field, add the tag to that layout file too, or move it into a partial such as `resources/views/partials/rybbit.antlers.html` and `{{ partial:rybbit }}` it from each layout. If your views use Blade (`layout.blade.php`), the same tag goes in the same place.

    To keep the site ID out of version control, put it in `.env` as `RYBBIT_SITE_ID` and use `{{ config:services:rybbit:site_id }}` after adding a `rybbit` entry to `config/services.php`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Static caching**: with `half` or `full` static caching enabled in `config/statamic/static_caching.php`, run `php please static:clear` after editing the layout, otherwise cached pages keep the old head.
* **Live Preview counts as visits**: the control panel's Live Preview renders your entry in an iframe at its real URL with a `token` query parameter. Editors' previews are tracked like any other visit, so check analytics from the live site rather than the control panel.
* **Control panel is not tracked**: `/cp` uses Statamic's own views, so the snippet never runs there.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Storyblok (/de/docs/guides/storyblok)





Storyblok is a headless CMS: it stores content and delivers it through its APIs, while your frontend renders the pages. The tracking snippet therefore goes into the frontend's root layout, not into Storyblok.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Storyblok [#add-the-snippet-to-storyblok]

    <Callout type="info">
      Storyblok has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Storyblok.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Remix](/docs/guides/react/remix)
        * [Gatsby](/docs/guides/react/gatsby)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>

    The script tracks client-side route changes automatically, so navigation between stories in any of these frameworks is counted without extra code.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Visual Editor previews count as visits**: the Visual Editor loads your frontend in an iframe at the **Preview URL** set under **Settings > Visual Editor**, appending `_storyblok` and `_storyblok_tk[...]` query parameters. Editors' preview sessions are tracked like real visitors. Point the Preview URL at a separate preview deployment registered as its own site in Rybbit, or leave the tag out of builds that use the preview token.
* **Preview parameters in tracked URLs**: if the same deployment serves both the live site and the Visual Editor, the `_storyblok` parameters show up in tracked page URLs. Add `data-track-query="false"` to the script tag to drop query strings.
* **The Storyblok app is not tracked**: the snippet only runs in your frontend, so time spent in `app.storyblok.com` never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Strapi (/de/docs/guides/strapi)





Strapi is a headless CMS: it exposes your content over a REST or GraphQL API and does not render your website. The tracking snippet therefore goes into the frontend that consumes the Strapi API, not into Strapi.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Strapi [#add-the-snippet-to-strapi]

    <Callout type="info">
      Strapi has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Strapi.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Strapi frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Nuxt is a popular Strapi frontend. Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby)
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **The admin panel is not tracked**: the Strapi admin at `/admin` is served by the Strapi server, not by your frontend, so it never loads the snippet. Content editors' activity does not appear in Rybbit, which is usually what you want.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# systeme.io (/de/docs/guides/systeme-io)





systeme.io has an account-wide **Tracking code** setting under **Settings > Sales Funnels** that adds code to every funnel page, plus a per-page **Tracking** section with a header field in the page editor. Use the account-wide setting unless you only want to track certain pages.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to systeme.io [#add-the-snippet-to-systemeio]

    <Tabs items="[&#x22;All funnels&#x22;, &#x22;One page&#x22;]">
      <Tab>
        1. Click your **profile picture** in the top-right corner and choose **Settings**.
        2. Select **Sales Funnels** in the left menu.
        3. Paste the snippet into the **Tracking code** box and click **Save**.

        The code is added to every page in every funnel on the account.
      </Tab>

      <Tab>
        1. Open the funnel, select the page in the list on the left and click **Edit page**.
        2. Click **Settings** in the upper-left corner of the editor and scroll to the **Tracking** section.
        3. Paste the snippet into the **header** field (the one for code that belongs between `<head>` and `</head>`).
        4. Save the page.
      </Tab>
    </Tabs>

    Paste only the `<script>` tag. systeme.io asks that custom code never include `<head>`, `<body>` or `<html>` tags of its own.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Duplicate pageviews**: the snippet is in both the account-wide Tracking code and a page's Tracking section. Keep one.
* **Not visible in preview**: custom code runs on the live page only. Open the published funnel URL to test.
* **Pages outside funnels**: the Sales Funnels tracking code covers funnel pages. Blog and course pages have their own settings, so add the snippet there if you want that traffic in the same site.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Tauri (/de/docs/guides/tauri)





Tauri v2 bundles your frontend into the app and serves it to the system webview. Install the `@rybbit/js` SDK in the frontend (or put the snippet in its `index.html`), then allow `https://app.rybbit.io` in the `app.security.csp` block of `src-tauri/tauri.conf.json`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Tauri [#add-the-snippet-to-tauri]

    <Callout type="info">
      Tauri's security guide advises against loading remote scripts such as CDN-hosted files. The SDK keeps all executable code inside the bundle, so it is the recommended method.
    </Callout>

    <Tabs items="[&#x22;@rybbit/js SDK&#x22;, &#x22;Script tag&#x22;]">
      <Tab>
        1. Install the package in your frontend project:

        ```bash
        npm install @rybbit/js
        ```

        2. Initialise it once in the frontend entry file (`src/main.ts` or equivalent):

        ```ts title="src/main.ts"
        import rybbit from "@rybbit/js";

        await rybbit.init({
          analyticsHost: "https://app.rybbit.io/api",
          siteId: "YOUR_SITE_ID",
        });
        ```

        3. Allow the analytics host in `connect-src`. Keep `ipc:` and `http://ipc.localhost`, which Tauri needs for frontend-to-Rust calls:

        ```json title="src-tauri/tauri.conf.json"
        {
          "app": {
            "security": {
              "csp": {
                "default-src": "'self'",
                "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]
              }
            }
          }
        }
        ```
      </Tab>

      <Tab>
        1. Paste the snippet into the `<head>` of your frontend's `index.html`:

        ```html title="index.html"
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        2. Allow the host in both `script-src` and `connect-src`:

        ```json title="src-tauri/tauri.conf.json"
        {
          "app": {
            "security": {
              "csp": {
                "default-src": "'self'",
                "script-src": ["'self'", "https://app.rybbit.io"],
                "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    If `app.security.csp` is unset, Tauri applies no CSP and neither change is needed. Route changes inside the app are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Works in `tauri dev` but not in the built app on macOS, Linux or iOS**: in development the frontend is served from your dev server (`http://localhost:1420` by default), which is a normal http origin. Production builds serve it from `http://tauri.localhost` on Windows and Android but from the custom scheme `tauri://localhost` on macOS, Linux and iOS. Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so requests from `tauri://localhost` are blocked by the webview. On Windows and Android, `app.windows[].useHttpsScheme: true` switches the origin to `https://tauri.localhost`; both forms work.
* **CSP violation in the webview console**: the message names the blocked directive. Add `https://app.rybbit.io` there; the SDK only needs `connect-src`, the script tag also needs `script-src`.
* **Object vs string CSP**: `app.security.csp` accepts either a single policy string or the object form shown above. Do not mix the two.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Teachable (/de/docs/guides/teachable)





Teachable adds tracking scripts through **Code Snippets** in the school admin, where the **Head Code Snippets** section places code inside the `<head>` of every page of your school. Code Snippets are available on the Builder plan and above.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Teachable [#add-the-snippet-to-teachable]

    1. In the school admin, go to **Site > Code Snippets**.
    2. Paste the snippet into the **Head Code Snippets** section, which applies to all pages and all users.
    3. Click **Save**.

    The **Logged In Snippets** and **Logged Out Snippets** sections restrict code to one audience. Leave them empty for Rybbit so students and prospects are tracked alike; if you only want to measure the public site, use **Logged Out Snippets** instead of the head section.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Code Snippets is missing from the Site menu**: it needs the Builder plan or higher. Schools on lower plans cannot add custom scripts.
* **Checkout and login pages are not tracked**: head code snippets do not apply to SSO-based login or checkout pages served from `sso.teachable.com`. Pages on your school domain, including the course area, are covered.
* **Snippet pasted into a lesson's Custom HTML block**: that block only affects one lesson. Use **Code Snippets** for site-wide tracking.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Thinkific (/de/docs/guides/thinkific)





Thinkific adds custom scripts through the **Site Footer Code** field under **Settings > Code & Analytics**. The code runs at the bottom of every page, including the Course Player, and editing it is available on paid plans (Basic or higher). Placing the snippet in the footer rather than the head is fine: it loads with `defer`, so timing is the same.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Thinkific [#add-the-snippet-to-thinkific]

    1. In the admin dashboard, go to **Settings** and open the **Code & Analytics** tab.
    2. Paste the snippet into **Site Footer Code**.
    3. Save.

    See Thinkific's [Site Footer Code](https://support.thinkific.com/hc/en-us/articles/360030724953-Site-Footer-Code) article for the field's current limits. Lesson changes inside the Course Player happen without a page reload; Rybbit tracks them as pageviews automatically as the URL changes.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Field is read-only or missing**: editing Site Footer Code needs a paid plan (Basic or higher).
* **Checkout is not tracked**: Site Footer Code does not run on Performance Checkout pages, so purchases complete outside Rybbit's view. Track the enrolment from the first page a student lands on after checkout, or use a webhook on your side.
* **Community pages are not tracked**: pages where students post and comment, and direct-messaging pages, are excluded from Site Footer Code by default.
* **Per-page footer code**: individual site pages also accept footer code in their page settings. Keep the site-wide field as the single place for the snippet so pages are not tracked twice.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ThriveCart (/de/docs/guides/thrivecart)





ThriveCart lets you add custom scripts to each checkout page, and its success page is where the purchase event goes. ThriveCart strips `data-*` attributes from script tags, so the site ID must travel in the script URL, as it does in the snippet below.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ThriveCart [#add-the-snippet-to-thrivecart]

    1. In your ThriveCart dashboard, open the checkout page you want to track.
    2. Open **Settings > Tracking**, the custom scripts section.
    3. Paste the snippet into the header scripts field and save.

    Repeat for each checkout page. If checkout runs on a subdomain such as `sales.yourdomain.com` and your main site uses the same site ID, both are tracked as one site, so funnels can follow a visitor from your site through to the purchase.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

ThriveCart also interferes with how inline events fire, so the success-page script below loads the tracker itself if it is missing, waits for it, and uses `sessionStorage` to send the event once per browser session even if the visitor refreshes or navigates back.

Add it to the checkout's **success page** and fill in the values at the top:

```html
<script>
(function () {
  var EVENT_NAME = "purchase";
  var PAYLOAD = { content_name: "Your Product Name", value: 97.0, currency: "USD" };
  var SITE_ID = "YOUR_SITE_ID";
  var SCRIPT_SRC = "https://app.rybbit.io/api/script.js?siteId=" + SITE_ID;

  // Send once per session, even on refresh or back navigation
  var SENT_KEY = "rybbit_" + EVENT_NAME + "_sent_v1";
  try {
    if (sessionStorage.getItem(SENT_KEY) === "1") return;
    sessionStorage.setItem(SENT_KEY, "1");
  } catch (e) {}

  function isReady() {
    return window.rybbit && typeof window.rybbit.event === "function";
  }
  function send() {
    window.rybbit.event(EVENT_NAME, PAYLOAD);
  }
  function waitThenSend(timeoutMs) {
    var start = Date.now();
    (function check() {
      if (isReady()) return send();
      if (Date.now() - start < timeoutMs) setTimeout(check, 150);
    })();
  }

  if (isReady()) return send();
  if (!document.querySelector('script[src="' + SCRIPT_SRC + '"]')) {
    var s = document.createElement("script");
    s.src = SCRIPT_SRC;
    s.defer = true;
    document.head.appendChild(s);
  }
  waitThenSend(8000);
})();
</script>
```

* `EVENT_NAME`: the event name, for example `purchase` or `checkout_complete`.
* `PAYLOAD`: `content_name` (product name), `value` (amount) and `currency` (`USD`, `GBP`, `EUR` and so on).
* `SITE_ID`: your Rybbit site ID.

Selling several products? The payload is fixed per page, so use a separate success page per product, or fill `PAYLOAD` from ThriveCart's dynamic variables where they are available.

## Troubleshooting [#troubleshooting]

* **Script attributes are stripped**: ThriveCart removes `data-*` attributes, so [script attributes](/docs/script#script-attributes) such as `data-skip-patterns` do not work here. Keep the site ID in the URL.
* **Duplicate purchase events**: the script is guarded by `sessionStorage`. If you still see duplicates, make sure the event script is on the success page only once, and clear session storage before testing again.
* **Script blocked**: if `script.js` never loads, try the footer scripts field instead of the header, or ask ThriveCart support to confirm custom scripts are enabled on your account.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# TYPO3 (/de/docs/guides/typo3)





TYPO3 sitepackages build the page `<head>` from TypoScript rather than an HTML template, so the snippet is added as a `page.includeJS` entry in your sitepackage's `setup.typoscript`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to TYPO3 [#add-the-snippet-to-typo3]

    1. Open your main TypoScript setup file, usually `<sitepackage>/Configuration/TypoScript/setup.typoscript`. It is the file that already contains `page = PAGE`. The same TypoScript can also live in a TypoScript record in the backend.

    2. Add the script to the `page` object:

       ```
       page = PAGE
       page {
         includeJS {
           rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
           rybbit.defer = 1
         }
       }
       ```

       Because the Site ID is part of the URL, no `data-*` attribute is needed, so this works on every supported TYPO3 version. Per-include attributes on `includeJS` only exist in TYPO3 12.1+.

    3. To track production only, wrap the include in an `applicationContext` condition:

       ```
       [applicationContext == "Production"]
       page.includeJS.rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
       page.includeJS.rybbit.defer = 1
       [END]
       ```

    4. Optionally keep the Site ID and instance URL in `constants.typoscript` (or a TypoScript record) so the setup file can be committed without site-specific values:

       ```
       # constants.typoscript
       rybbit {
         host = https://app.rybbit.io
         siteId = YOUR_SITE_ID
       }

       # setup.typoscript
       page.includeJS.rybbit = {$rybbit.host}/api/script.js?siteId={$rybbit.siteId}
       page.includeJS.rybbit.defer = 1
       ```

    5. Deploy the sitepackage, or set `applicationContext` accordingly, and flush the TYPO3 caches.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Script not in the page source**: TYPO3 caches rendered pages. Flush caches from the backend toolbar or with `vendor/bin/typo3 cache:flush` after changing TypoScript.
* **Wrong TypoScript file**: if several files define `page`, check the resulting `page.includeJS` in the TypoScript object browser in the backend to see which definition wins.
* **Condition never matches**: the `applicationContext` is set through the `TYPO3_CONTEXT` environment variable. If it is unset, TYPO3 runs as `Production` and the script loads everywhere.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Umbraco (/de/docs/guides/umbraco)





Umbraco renders pages with Razor templates stored as `.cshtml` files in the `Views` folder and edited in the backoffice under **Settings > Templates**. A fresh install has no templates until you create one, so the snippet goes into the master (layout) template that your page templates set as their `Layout`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Umbraco [#add-the-snippet-to-umbraco]

    1. In the backoffice, open the **Settings** section and expand **Templates**.
    2. Open the master template that the other templates use as their layout (named `Master&#x60; in Umbraco's own tutorial). If you have none yet, click &#x2A;*...** next to **Templates**, choose **Create**, and move the shared `<html>`, `<head>` and `<body>` markup into it.
    3. Add the tag before `</head>` and click **Save**:

    ```razor title="Views/Master.cshtml"
    @using Umbraco.Cms.Web.Common.PublishedModels;
    @inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
    @{
        Layout = null;
    }
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8" />
        <title>@Model.Name</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        @RenderBody()
    </body>
    </html>
    ```

    4. Check that each page template points at it, for example `Layout = "Master.cshtml";`. Templates with `Layout = null;` render their own `<head>` and need the tag added directly.

    Saving in the backoffice writes the same file to `Views/Master.cshtml` in the project, so you can also edit it in your IDE and commit it.

    To keep the site ID out of the template, put it in `appsettings.json` and read it with `@Configuration["Rybbit:SiteId"]` after injecting `IConfiguration`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Change not visible**: Razor views are compiled on first request; if you edited the file outside the backoffice on a published site, restart the app or redeploy. Also clear any output cache or CDN in front of the site.
* **Preview counts as visits**: the backoffice **Preview** button renders your template with unpublished content, so editors' previews are tracked like any other visit. Wrap the tag in `@if (!UmbracoContext.InPreviewMode) { ... }` to leave them out.
* **Backoffice is not tracked**: `/umbraco` is a separate app that does not use your templates, so editing time never appears in Rybbit.
* **Several master templates**: a multi-site install with one layout per site needs the tag in each, or in a partial view rendered from every layout with `@await Html.PartialAsync("Rybbit")`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Unbounce (/de/docs/guides/unbounce)





Unbounce's **Script Manager** applies a script to every page on a domain, including pages you publish later, so that is where the snippet goes. If you only want to track a single Classic Builder page, the page-level **Javascripts** dialog works too.

<Callout type="warn">
  Custom scripts and pixels are not available on the Starter plan; you need Build or higher. Script Manager also requires a connected custom domain: it does not apply to pages on the `unbouncepages.com` test domain.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Unbounce [#add-the-snippet-to-unbounce]

    <Tabs items="[&#x22;Script Manager&#x22;, &#x22;Classic Builder page&#x22;]">
      <Tab>
        1. In the left menu, click **Settings**, then **Script Manager**.
        2. Click **Add a Script**, choose **Custom Script**, give it a name and click **Add Script Details**.
        3. Set **Placement** to **Head** and **Included on** to **All** (main pages and confirmation dialogs).
        4. Paste the snippet into the editor.
        5. Tick the domain(s) the script should apply to on the right, then click **Save Changes**.

        The script is added to every page on those domains and to new pages published there later. If a page does not pick it up, republish that page.
      </Tab>

      <Tab>
        1. Open the page in the Classic Builder and click **Javascripts** in the bottom-left corner.
        2. Give the script a name and set **Placement** to **Head**.
        3. Paste the snippet and click **Done**.
        4. **Save**, then **Publish** (or **Republish**) the page. Custom scripts do not run in the builder or in Preview, only on the published page.

        Smart Builder pages have no page-level script dialog; use Script Manager for those.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Form submission [#form-submission]

Unbounce exposes `window.ub.hooks`, an unofficial hook that runs after a lead is recorded. Add this as a second Script Manager script (or page script) with placement **Before Body End Tag** to send a `lead` event with the page name and variant:

```html
<script>
window.ub.hooks.afterFormSubmit.push(function () {
  if (window.rybbit) {
    window.rybbit.event("lead", {
      page: window.ub.page.name,
      variant: window.ub.page.variantId
    });
  }
});
</script>
```

`window.ub.page.name`, `window.ub.page.variantId` and `window.ub.page.id` are available on every Unbounce page, so you can compare A/B variants in Rybbit without any other setup.

## Troubleshooting [#troubleshooting]

* **Script runs twice**: a script that is both in Script Manager and on an individual page loads twice. Remove the page-level copy and keep the Script Manager one.
* **Nothing on `unbouncepages.com`**: Script Manager only applies to custom domains. Add the snippet at page level to test on the Unbounce test domain.
* **Script Manager missing**: the account is on the Starter plan, which does not include custom scripts.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# v0 (/de/docs/guides/v0)





v0 generates Next.js apps, so there is no single `index.html` and no project setting for head code. The snippet goes into the root layout, `app/layout.tsx`, through a `next/script` tag that renders on every page. Ask v0 to add it or edit the file in the Code tab, then publish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to v0 [#add-the-snippet-to-v0]

    <Tabs items="[&#x22;Ask v0&#x22;, &#x22;Edit app/layout.tsx&#x22;]">
      <Tab>
        Paste this into the chat, with your site ID in place of the placeholder:

        ```text
        Add the Rybbit analytics script to the root layout (app/layout.tsx) using next/script with strategy="afterInteractive", so it loads on every page:
        https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
        ```

        Check the diff: the `<Script>` belongs in `app/layout.tsx`, not in a page or component.
      </Tab>

      <Tab>
        Select the **Code** tab in the preview toolbar, open `app/layout.tsx` and add the `Script` component inside `<body>`. The `defer` attribute from the snippet is not needed; the strategy handles timing.

        ```tsx title="app/layout.tsx"
        import Script from "next/script";

        export default function RootLayout({ children }: { children: React.ReactNode }) {
          return (
            <html lang="en">
              <body>
                {children}
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```

        Press **Cmd+S** / **Ctrl+S** to save.
      </Tab>
    </Tabs>

    Click **Publish** in the top right of the chat, then **Publish to Production**. Navigation through `<Link>` and `router.push()` is tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a client component. Guard the call, because v0 components can render on the server and the script loads after hydration.

```tsx title="components/signup-button.tsx"
"use client";

export function SignupButton() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Production has no script**: the preview updates on save, but the live site only changes after **Publish to Production**. Projects connected to GitHub go through a pull request that v0 merges before the production deployment runs.
* **v0 rewrote the layout**: a later prompt can regenerate `app/layout.tsx`. Add "keep the Rybbit Script tag in app/layout.tsx" to the project's custom instructions, and re-check the page source after large changes.
* **Pages Router**: if your project has `pages/` instead of `app/`, put the `Script` in `pages/_app.tsx` as shown in the [Next.js guide](/docs/guides/react/next-js).

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# VitePress (/de/docs/guides/vitepress)





VitePress has a `head` option in `.vitepress/config.ts` that adds tags to every page, which is where the snippet goes. A custom theme is the fallback when you need to load it conditionally at runtime.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to VitePress [#add-the-snippet-to-vitepress]

    <Tabs items="[&#x22;Config file&#x22;, &#x22;Custom theme&#x22;]">
      <Tab>
        Edit `.vitepress/config.ts` (or `.js` / `.mts`) and add the tag to `head`:

        ```typescript filename=".vitepress/config.ts"
        import { defineConfig } from "vitepress";

        export default defineConfig({
          // ... your other config
          head: [
            [
              "script",
              {
                src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                defer: "",
              },
            ],
          ],
        });
        ```

        <Callout type="info">
          The empty string for `defer` is intentional. VitePress renders it as a boolean attribute.
        </Callout>

        To track production only, make `head` conditional:

        ```typescript filename=".vitepress/config.ts"
        const isProd = process.env.NODE_ENV === "production";

        export default defineConfig({
          head: isProd
            ? [["script", { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: "" }]]
            : [],
        });
        ```
      </Tab>

      <Tab>
        If you need runtime control, inject the tag from a custom theme. Create or edit `.vitepress/theme/index.ts`:

        ```typescript filename=".vitepress/theme/index.ts"
        import { type Theme } from "vitepress";
        import DefaultTheme from "vitepress/theme";

        export default {
          extends: DefaultTheme,
          enhanceApp() {
            if (typeof window === "undefined") return;

            const el = document.createElement("script");
            el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
            el.defer = true;
            document.head.appendChild(el);
          },
        } satisfies Theme;
        ```

        The `window` check keeps the injector out of the server-side build.
      </Tab>
    </Tabs>

    VitePress navigates between pages client-side. Rybbit picks up those History API changes as pageviews, so no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in `vitepress dev`**: if you used the `isProd` guard, the tag only renders in `vitepress build`. Remove the guard to test locally.
* **Pageviews stop after navigation**: check the browser console for errors thrown by other `head` scripts or theme code; an exception during route change can block Rybbit's listener.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Webflow (/de/docs/guides/webflow)





Webflow accepts custom `<head>` code either site-wide in **Site settings → Custom code** or per page in the page settings. Either way the code only reaches the live site when you publish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Webflow [#add-the-snippet-to-webflow]

    <Tabs items="[&#x22;Site-wide&#x22;, &#x22;Single page&#x22;]">
      <Tab value="Site-wide">
        1. Open your project and go to **Site settings → Custom code**.
        2. Paste the snippet into **Head code**.
        3. Click **Save**, then **Publish** the site.
      </Tab>

      <Tab value="Single page">
        Use this when you only want to track specific pages.

        1. In the Designer, open the page's **Settings** (cog icon next to the page name).
        2. Scroll to **Custom code** and paste the snippet into **Inside `<head>` tag**.
        3. Click **Save**, then **Publish** the site.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Give the element an **ID** in the Designer (**Settings** panel → **General** → **ID**), then attach a listener in **Site settings → Custom code → Footer code** or in an **Embed** element on that page:

```html
<script>
  document.addEventListener("DOMContentLoaded", function () {
    var button = document.getElementById("my-special-button");
    if (!button) return;
    button.addEventListener("click", function () {
      window.rybbit?.event("button_click", {
        button_id: "my-special-button",
        page_path: window.location.pathname,
      });
    });
  });
</script>
```

The same pattern works for a Form Block's `submit` event. Webflow handles form submission itself, so this fires on the submit attempt, not on confirmed success.

## Troubleshooting [#troubleshooting]

* **Changes not showing on the live site**: custom code is staged until you **Publish**. Check the published site, not the Designer preview.
* **Interactions that show or hide sections** without changing the URL produce a single pageview. Track those states as custom events, or call `window.rybbit.pageview()` from your own script when they appear.
* **Scripts that read the DOM** belong in **Footer code**, not **Head code**, so the elements exist when they run.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Weebly (/de/docs/guides/weebly)





Weebly (now part of Square) has site-wide **Header Code** and **Footer Code** fields under its SEO settings. Header code is printed into the `<head>` of every page, so the snippet goes there and no theme edits are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Weebly [#add-the-snippet-to-weebly]

    1. Open your site in the Weebly editor and go to **Settings > SEO**.
    2. Paste the snippet into **Header Code** and click **Save**.
    3. Click **Publish**. Header code changes only reach the live site after you publish.

    If your editor has no **Settings** tab, the same header-code option is under **Website > General Settings** in the Square dashboard.

    Site-level header code covers every page, including blog posts. Each page also has its own **Header Code** box in its page settings; that one is for page-specific code and is not needed for the snippet.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the page source**: the site was not republished. Click **Publish** after every change to header code.
* **Snippet appears twice**: it was added both site-wide and on individual pages. Keep only the site-level entry under **Settings > SEO**.
* **Footer Code instead of Header Code**: both fields are included on every page, so the snippet works from either, but the footer loads later and misses visitors who leave early.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Wix (/de/docs/guides/wix)





Wix adds third-party scripts through the **Custom Code** panel in the site dashboard, where you choose which pages load the code and where in the document it goes.

<Callout type="warn">
  Custom code requires a **Wix Premium plan** and a **connected domain**. It is not available on free Wix sites.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Wix [#add-the-snippet-to-wix]

    1. Open your site's dashboard and go to **Settings**.
    2. Open **Custom Code** (under **Advanced**). Older dashboards list it as **Tracking Tools & Analytics** under **Marketing & SEO**.
    3. Click **+ Add Custom Code** and paste the snippet into the code box.
    4. Name the code, for example `Rybbit`.
    5. Under **Add Code to Pages**, choose **All pages** and **Load code once**. The script tracks Wix's client-side navigation itself, so loading it on every page change would inject it repeatedly.
    6. Under **Place Code in**, choose **Head**.
    7. Click **Apply**.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Custom Code is missing from Settings**: the site has no Premium plan or no connected domain. Both are required before the panel appears.
* **Duplicate pageviews**: the code was added with **Load code on each new page**. Edit the entry and switch to **Load code once**.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# WooCommerce (/de/docs/guides/woocommerce)





WooCommerce runs on WordPress, so the snippet goes in the same way as on any WordPress site. What this guide adds is the WooCommerce action hooks that send purchases, add-to-carts, product views and checkouts to Rybbit as custom events.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to WooCommerce [#add-the-snippet-to-woocommerce]

    Follow the [WordPress guide](/docs/guides/wordpress) to add the snippet. If you plan to track the e-commerce events below, use the `functions.php` or mini-plugin method there: the event hooks are PHP and belong in the same file.

    ```php
    function rybbit_add_tracking_script() {
        ?>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        <?php
    }
    add_action( 'wp_head', 'rybbit_add_tracking_script' );
    ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

WooCommerce fires PHP action hooks at each stage of the shopping flow. The snippets below print a small inline script from those hooks. They wait for `DOMContentLoaded` because the tracking script is loaded with `defer`, so `window.rybbit` does not exist while the page is still parsing.

<Callout type="warn">
  Add these to your &#x2A;*child theme's `functions.php`** or a site-specific plugin, never to the parent theme.
</Callout>

#### Purchase [#purchase]

`woocommerce_thankyou` fires on the order-received page with the order ID.

```php
add_action( 'woocommerce_thankyou', 'rybbit_track_purchase', 10, 1 );
function rybbit_track_purchase( $order_id ) {
    $order = wc_get_order( $order_id );
    if ( ! $order ) {
        return;
    }

    $items = array();
    foreach ( $order->get_items() as $item ) {
        $product = $item->get_product();
        $items[] = array(
            'item_id'   => $product && $product->get_sku() ? $product->get_sku() : $item->get_product_id(),
            'item_name' => $item->get_name(),
            'price'     => (float) $order->get_line_subtotal( $item, false, false ),
            'quantity'  => (int) $item->get_quantity(),
        );
    }

    $purchase = array(
        'transaction_id' => $order->get_order_number(),
        'value'          => (float) $order->get_total(),
        'tax'            => (float) $order->get_total_tax(),
        'shipping'       => (float) $order->get_shipping_total(),
        'currency'       => $order->get_currency(),
        'items'          => $items,
    );
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function () {
        window.rybbit.event('purchase', <?php echo wp_json_encode( $purchase ); ?>);
    });
    </script>
    <?php
}
```

Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.

#### Add to cart [#add-to-cart]

Two hooks cover both paths: the product-page form submit, and WooCommerce's `added_to_cart` jQuery event for AJAX buttons on shop and category pages.

```php
// Single product page: track on form submit
add_action( 'woocommerce_after_add_to_cart_button', 'rybbit_track_add_to_cart' );
function rybbit_track_add_to_cart() {
    global $product;
    if ( ! $product instanceof WC_Product ) {
        return;
    }
    $data = array(
        'item_id'   => $product->get_sku() ? $product->get_sku() : $product->get_id(),
        'item_name' => $product->get_name(),
        'price'     => (float) $product->get_price(),
        'currency'  => get_woocommerce_currency(),
    );
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function () {
        var form = document.querySelector('form.cart');
        if (!form) return;
        form.addEventListener('submit', function () {
            var data = <?php echo wp_json_encode( $data ); ?>;
            var qty = form.querySelector('input.qty');
            data.quantity = qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1;
            window.rybbit.event('add_to_cart', data);
        });
    });
    </script>
    <?php
}

// AJAX add-to-cart buttons on shop and category pages
add_action( 'wp_footer', 'rybbit_track_ajax_add_to_cart' );
function rybbit_track_ajax_add_to_cart() {
    if ( is_admin() ) {
        return;
    }
    ?>
    <script>
    jQuery(document.body).on('added_to_cart', function (event, fragments, cartHash, $button) {
        if (!$button || !$button.length) return;
        window.rybbit.event('add_to_cart', {
            item_id: $button.data('product_id'),
            quantity: $button.data('quantity') || 1,
            source: 'ajax_add_to_cart'
        });
    });
    </script>
    <?php
}
```

The AJAX handler only sees the product ID and quantity from the button's `data-*` attributes. Add attributes to the button in your theme if you also want name and price.

#### View product and begin checkout [#view-product-and-begin-checkout]

The same pattern works for the remaining hooks:

* `woocommerce_after_single_product_summary` runs on product pages. Guard with `is_product()`, then send `view_item` with `item_id`, `item_name`, `price` and `currency` from the global `$product`.
* `woocommerce_before_checkout_form` runs on the checkout page. Build `begin_checkout` from `WC()->cart`: loop over `get_cart()` for the items (each `$cart_item['data']` is the product, `$cart_item['quantity']` the quantity), with `value` from `$cart->get_total( 'edit' )` and `currency` from `get_woocommerce_currency()`.

## Troubleshooting [#troubleshooting]

* **Events fire before the tracker loads**: keep the tracking snippet in `wp_head` and the `DOMContentLoaded` wrapper in place. Deferred scripts run before `DOMContentLoaded`, so `window.rybbit` is ready by then; calling it from a bare inline script drops the event.
* **AJAX carts and mini-carts**: themes that update the cart without a page load never hit the PHP hooks, so rely on the `added_to_cart` listener for those and test each add-to-cart path.
* **Other analytics plugins**: plugins that also print e-commerce data layers can conflict. Test with a real order after enabling both.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# WordPress (/de/docs/guides/wordpress)





WordPress has no built-in header-code setting, so the snippet goes in through a plugin such as **WPCode** or through your theme's `functions.php` or `header.php`. Every method below works on self-hosted WordPress.org sites; on WordPress.com you need the Business plan or higher before you can install plugins or add custom JavaScript.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to WordPress [#add-the-snippet-to-wordpress]

    <Callout type="warn">
      If you edit theme files, edit a **child theme**. Changes to a parent theme's `functions.php` or `header.php` are lost on the next theme update.
    </Callout>

    <Tabs items="[&#x22;WPCode&#x22;, &#x22;functions.php&#x22;, &#x22;header.php&#x22;, &#x22;Mini plugin&#x22;]">
      <Tab>
        WPCode (formerly Insert Headers and Footers) is the recommended method: it survives theme updates, works with page builders, and is available on WordPress.com Business plans.

        1. Go to **Plugins > Add New**, search for "WPCode", then install and activate it.
        2. Go to **Code Snippets > Header & Footer** (**Settings > Insert Headers and Footers** in older versions).
        3. Paste the snippet into the **Header** box and click **Save Changes**.
      </Tab>

      <Tab>
        1. Go to **Appearance > Theme File Editor** and open your child theme's `functions.php`.
        2. Add this to the end of the file, replacing `YOUR_SITE_ID`:

        ```php
        function rybbit_add_tracking_script() {
            ?>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
            <?php
        }
        add_action( 'wp_head', 'rybbit_add_tracking_script' );
        ```

        3. Save the file.
      </Tab>

      <Tab>
        1. Go to **Appearance > Theme File Editor** and open your child theme's `header.php`.
        2. Paste the snippet just before the closing `</head>` tag:

        ```html
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        3. Save the file.
      </Tab>

      <Tab>
        A one-file plugin keeps the snippet in place through theme changes without touching theme files.

        1. Over FTP/SFTP or a file-manager plugin, create the folder `/wp-content/plugins/rybbit-analytics/`.
        2. Inside it, create `rybbit-analytics.php` with this content, replacing `YOUR_SITE_ID`:

        ```php
        <?php
        /**
         * Plugin Name: Rybbit Analytics
         * Description: Adds the Rybbit tracking script to every page
         * Version: 1.0
         */

        function rybbit_add_tracking_script() {
            ?>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
            <?php
        }
        add_action( 'wp_head', 'rybbit_add_tracking_script' );
        ```

        3. Go to **Plugins** and activate **Rybbit Analytics**.
      </Tab>
    </Tabs>

    Running WooCommerce? Once the snippet is in place, see the [WooCommerce guide](/docs/guides/woocommerce) for purchase and add-to-cart events.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Caching plugins**: after saving the snippet, purge WP Super Cache, W3 Total Cache, LiteSpeed Cache or whichever cache plugin you run, plus any CDN cache such as Cloudflare, before you check the page source.
* **Script optimisers**: "Delay JavaScript execution" features in WP Rocket, Perfmatters and FlyingPress rebuild script tags and drop `data-*` attributes, which is why the snippet passes the site ID in the URL (`?siteId=`). If tracking still fails, exclude `app.rybbit.io` from optimisation: Autoptimize's exclusion list, WP Rocket's JavaScript optimisation and delay-JS exclusions, Perfmatters / FlyingPress delay-JS exclusions, LiteSpeed Cache JS excludes, SG Optimizer combine/minify.
* **Page builders** (Elementor, Divi, WPBakery, Beaver Builder): add the snippet with WPCode rather than a builder's custom HTML block. Builders sanitise HTML and can strip attributes from script tags.
* **Security plugins**: Wordfence, Sucuri and similar plugins can block external scripts. Add `app.rybbit.io` to the allowlist.
* **WordPress.com plans**: Free, Personal and Premium plans cannot add custom JavaScript. Upgrade to Business or eCommerce and use the WPCode method.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Zola (/de/docs/guides/zola)





Zola pages extend a base Tera template, normally `templates/base.html`, so the snippet goes in that file's `<head>`. Keep the site ID in the `[extra]` section of `config.toml`, which every template can read as `config.extra`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Zola [#add-the-snippet-to-zola]

    1. Add your site ID under `[extra]` in `config.toml`. `rybbit_instance_url` is only needed if you self-host:

       ```toml title="config.toml"
       [extra]
       rybbit_site_id = "YOUR_SITE_ID"
       rybbit_instance_url = "https://app.rybbit.io"
       ```

    2. Open `templates/base.html` and add the tag inside `<head>`. The `config.mode` check keeps the script out of `zola serve`, so local development is not tracked:

       ```html title="templates/base.html"
       <head>
         ...
         {% if config.mode == "build" %}
           <script src="{{ config.extra.rybbit_instance_url }}/api/script.js?siteId={{ config.extra.rybbit_site_id }}" defer></script>
         {% endif %}
       </head>
       ```

       If a theme owns `base.html`, copy it from `themes/<theme>/templates/base.html` into your own `templates/` directory first. A template in your site with the same name overrides the theme's copy, so the theme can be updated without losing the change.

    3. Build and deploy the generated `public/` directory:

       ```bash
       zola build
       ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `zola serve` sets `config.mode` to `serve`, so the guard removes the tag. Check the output of `zola build` instead.
* **`config.mode` is not defined**: older Zola releases do not expose it. Upgrade, or drop the `if` block and accept local pageviews.
* **Pages without the tag**: templates that do not `{% extends "base.html" %}` (a custom `404.html`, or a section template that builds its own `<head>`) need the tag added separately.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Astro Proxy Setup (/de/docs/proxy-guide/astro)





Astro's middleware feature makes it simple to proxy Rybbit tracking. This guide shows how to set up server-side request proxying in your Astro application.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Astro middleware allows you to intercept and modify requests before they're handled, making it perfect for creating a transparent analytics proxy.

**What you'll achieve:**

* Proxy Rybbit endpoints through your Astro site
* Forward necessary headers for accurate tracking
* Simple configuration in `astro.config.mjs`
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Astro 2.0 or later (with SSR or hybrid rendering enabled)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

<Callout type="warn">
  This guide requires SSR (Server-Side Rendering) or hybrid mode. Static sites cannot proxy requests server-side. For static sites on platforms like Vercel or Netlify, use their platform-specific proxy configurations.
</Callout>

## Implementation [#implementation]

<Steps>
  ### Enable SSR in Astro [#enable-ssr-in-astro]

  Update `astro.config.mjs` to enable SSR:

  ```javascript
  // astro.config.mjs
  import { defineConfig } from 'astro/config';
  import node from '@astrojs/node';

  export default defineConfig({
    output: 'server', // or 'hybrid'
    adapter: node({
      mode: 'standalone',
    }),
  });
  ```

  Install the Node adapter if not already installed:

  ```bash
  npm install @astrojs/node
  ```

  ### Configure Environment Variables [#configure-environment-variables]

  Create or update `.env`:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  ### Create Middleware [#create-middleware]

  Create `src/middleware.ts` (or `.js` for JavaScript):

  ```typescript
  // src/middleware.ts
  import type { MiddlewareHandler } from 'astro';

  const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';

  export const onRequest: MiddlewareHandler = async (context, next) => {
    const { request } = context;
    const url = new URL(request.url);

    // Check if this is an analytics request
    if (url.pathname.startsWith('/analytics/')) {
      return proxyToRybbit(request, url.pathname);
    }

    // Continue with normal request handling
    return next();
  };

  async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
    try {
      // Map paths: /analytics/* → /api/*
      let rybbitPath = pathname.replace('/analytics/', '/api/');

      const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;

      // Get client IP from headers
      const forwardedFor = request.headers.get('x-forwarded-for');
      const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';

      // Forward request
      const proxyHeaders = new Headers(request.headers);
      proxyHeaders.set('X-Real-IP', clientIp);
      proxyHeaders.set('X-Forwarded-For', clientIp);

      const response = await fetch(rybbitUrl, {
        method: request.method,
        headers: proxyHeaders,
        body: request.method !== 'GET' ? await request.text() : undefined,
      });

      // Return proxied response
      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
      });
    } catch (error) {
      console.error('Rybbit proxy error:', error);
      return new Response('Analytics proxy error', { status: 500 });
    }
  }
  ```

  For JavaScript projects:

  ```javascript
  // src/middleware.js
  const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';

  export const onRequest = async (context, next) => {
    const { request } = context;
    const url = new URL(request.url);

    if (url.pathname.startsWith('/analytics/')) {
      return proxyToRybbit(request, url.pathname);
    }

    return next();
  };

  async function proxyToRybbit(request, pathname) {
    try {
      // Map paths: /analytics/* → /api/*
      let rybbitPath = pathname.replace('/analytics/', '/api/');

      const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;
      const forwardedFor = request.headers.get('x-forwarded-for');
      const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';

      const proxyHeaders = new Headers(request.headers);
      proxyHeaders.set('X-Real-IP', clientIp);
      proxyHeaders.set('X-Forwarded-For', clientIp);

      const response = await fetch(rybbitUrl, {
        method: request.method,
        headers: proxyHeaders,
        body: request.method !== 'GET' ? await request.text() : undefined,
      });

      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
      });
    } catch (error) {
      console.error('Rybbit proxy error:', error);
      return new Response('Analytics proxy error', { status: 500 });
    }
  }
  ```

  ### Update Your Layout [#update-your-layout]

  Add the tracking script to your layout:

  ```astro
  ---
  // src/layouts/Layout.astro
  const { title } = Astro.props;
  ---

  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width" />
      <title>{title}</title>

      <!-- Rybbit Analytics -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
    </head>
    <body>
      <slot />
    </body>
  </html>
  ```

  ### Start Development Server [#start-development-server]

  ```bash
  npm run dev
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Open your site** in a browser with Developer Tools
  2. **Check Network tab**: Requests should go to `/analytics/*`
  3. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Astro middleware intercepts requests before they're processed:

1. Request to `/analytics/script.js` enters middleware
2. Middleware proxies to `https://app.rybbit.io/api/script.js`
3. Client IP headers are preserved
4. Response is returned to browser

## Advanced Configuration [#advanced-configuration]

### Caching with Astro [#caching-with-astro]

Add caching for scripts:

```typescript
// src/middleware.ts
const cache = new Map<string, { response: Response; timestamp: number }>();
const CACHE_TTL = 3600000; // 1 hour in milliseconds

async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
  // Cache GET requests for scripts
  if (request.method === 'GET' && pathname.endsWith('.js')) {
    const cached = cache.get(pathname);

    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
      return cached.response.clone();
    }
  }

  // ... proxy logic

  // Cache the response
  if (request.method === 'GET' && pathname.endsWith('.js')) {
    cache.set(pathname, {
      response: response.clone(),
      timestamp: Date.now(),
    });
  }

  return response;
}
```

### Conditional Proxying [#conditional-proxying]

Only proxy in production:

```typescript
export const onRequest: MiddlewareHandler = async (context, next) => {
  const { request } = context;
  const url = new URL(request.url);

  // Only proxy in production
  if (import.meta.env.PROD && url.pathname.startsWith('/analytics/')) {
    return proxyToRybbit(request, url.pathname);
  }

  return next();
};
```

### Error Logging [#error-logging]

Add detailed error logging:

```typescript
async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
  try {
    // ... proxy logic
  } catch (error) {
    const errorDetails = {
      message: error instanceof Error ? error.message : 'Unknown error',
      pathname,
      method: request.method,
      timestamp: new Date().toISOString(),
    };

    console.error('Rybbit proxy error:', errorDetails);

    // Return error response
    return new Response(JSON.stringify({ error: 'Analytics proxy error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}
```

## Troubleshooting [#troubleshooting]

### Middleware not running [#middleware-not-running]

**Problem**: Requests bypass middleware.

**Solution**:

1. Ensure SSR or hybrid mode is enabled in `astro.config.mjs`
2. Verify middleware file is in `src/middleware.ts` (not in subdirectory)
3. Check adapter is installed: `npm install @astrojs/node`

### Static build issues [#static-build-issues]

**Problem**: Build fails or proxy doesn't work in production.

**Solution**:
Middleware requires server-side rendering. Ensure:

```javascript
// astro.config.mjs
export default defineConfig({
  output: 'server', // Required for middleware
  adapter: node({
    mode: 'standalone',
  }),
});
```

### Environment variables not loading [#environment-variables-not-loading]

**Problem**: `RYBBIT_HOST` is undefined.

**Solution**:

1. Check `.env` file is in project root
2. Use `import.meta.env.RYBBIT_HOST` (not `process.env`)
3. For production, set environment variables in your hosting platform

## Deployment [#deployment]

### Vercel [#vercel]

Deploy with Vercel adapter:

```bash
npm install @astrojs/vercel
```

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});
```

### Netlify [#netlify]

Deploy with Netlify adapter:

```bash
npm install @astrojs/netlify
```

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify/functions';

export default defineConfig({
  output: 'server',
  adapter: netlify(),
});
```

### Node.js Server [#nodejs-server]

For self-hosting:

```bash
npm run build
node ./dist/server/entry.mjs
```

## Related Resources [#related-resources]

* [Astro Integration Guide](/docs/guides/astro) - General Astro integration
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Astro Middleware](https://docs.astro.build/en/guides/middleware/) - Official Astro docs


# Caddy Proxy Setup (/de/docs/proxy-guide/caddy)





Caddy is a powerful web server with automatic HTTPS that makes reverse proxying simple and secure. This guide shows how to configure Caddy to proxy Rybbit tracking through your own domain.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Caddy's `reverse_proxy` directive makes it incredibly easy to proxy requests. Combined with automatic HTTPS via Let's Encrypt, Caddy provides a secure, low-configuration solution for proxying analytics.

**What you'll achieve:**

* Automatic HTTPS with Let's Encrypt
* Simple reverse proxy configuration
* Header forwarding for accurate tracking
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Caddy installed (version 2.0 or later)
* Domain pointing to your server
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID (found in your dashboard)

<Callout type="info">
  Caddy automatically obtains and renews SSL certificates from Let's Encrypt. No manual SSL configuration needed!
</Callout>

## Implementation [#implementation]

<Steps>
  ### Configure Caddyfile [#configure-caddyfile]

  Add or update your Caddyfile with the analytics proxy configuration:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'Simplified with Handle Path']">
    <Tab>
      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          # Your main site configuration
          # ...

          # Rybbit Analytics Proxy
          # Main tracking script
          handle /analytics/script.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up X-Forwarded-Proto {scheme}
              }
              rewrite * /api/script.js
          }

          # Session replay script
          handle /analytics/replay.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/replay.js
          }

          # Web Vitals metrics script
          handle /analytics/metrics.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/metrics.js
          }

          # Event tracking endpoint
          handle /analytics/track {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/track
          }

          # User identification endpoint
          handle /analytics/identify {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/identify
          }

          # Session replay recording
          handle /analytics/session-replay/record/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/session-replay/record{path}
          }

          # Site configuration
          handle /analytics/site/tracking-config/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/site/tracking-config{path}
          }
      }
      ```

      <Callout type="info">
        Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
      </Callout>
    </Tab>

    <Tab>
      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          # Main tracking script
          handle /analytics/script.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/script.js
          }

          # Event tracking
          handle /analytics/track {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/track
          }
      }
      ```
    </Tab>

    <Tab>
      Caddy 2.4+ supports a cleaner syntax with `handle_path`:

      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          handle_path /analytics/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api{uri}
          }
      }
      ```

      This proxies all `/analytics/*` requests to `https://app.rybbit.io/api/*`.
    </Tab>
  </Tabs>

  ### Validate Caddyfile [#validate-caddyfile]

  Test your configuration for syntax errors:

  ```bash
  caddy validate --config /etc/caddy/Caddyfile
  ```

  You should see:

  ```
  Valid configuration
  ```

  ### Reload Caddy [#reload-caddy]

  Apply the changes by reloading Caddy:

  ```bash
  sudo caddy reload --config /etc/caddy/Caddyfile
  ```

  Or if using systemd:

  ```bash
  sudo systemctl reload caddy
  ```

  <Callout type="info">
    Caddy will automatically obtain an SSL certificate from Let's Encrypt on first request if one doesn't exist.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to load the script from your proxied domain:

  ```html
  <!DOCTYPE html>
  <html>
  <head>
      <!-- ... other head elements -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      <!-- Your content -->
  </body>
  </html>
  ```

  Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.

  ### Verify the Setup [#verify-the-setup]

  Test your configuration:

  1. **Check Caddy is running**:
     ```bash
     sudo systemctl status caddy
     ```

  2. **Test script loading**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see `HTTP/2 200` with `content-type: application/javascript`.

  3. **Open your website** in a browser with Developer Tools and verify:
     * Script loads from `/analytics/script.js`
     * Tracking requests go to `/analytics/track`
     * Data appears in Rybbit dashboard
</Steps>

## How It Works [#how-it-works]

Caddy's `reverse_proxy` directive forwards requests to Rybbit's servers:

1. Browser requests `https://yourdomain.com/analytics/script.js`
2. Caddy matches the handle block
3. Rewrites the path to `/api/script.js`
4. Forwards to `https://app.rybbit.io/api/script.js` with proper headers
5. Returns response to browser

The Rybbit script auto-detects it's being served from your domain and sends all tracking to your domain's endpoints.

## Advanced Configuration [#advanced-configuration]

### Caching with Cache-Control [#caching-with-cache-control]

Add caching headers for better performance:

```txt
yourdomain.com {
    # Scripts - cache for 1 hour
    handle /analytics/script.js {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/script.js
        header Cache-Control "public, max-age=3600"
    }

    # Config - cache for 5 minutes
    handle /analytics/site/tracking-config/* {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/site/tracking-config{path}
        header Cache-Control "public, max-age=300"
    }

    # Tracking - no cache
    handle /analytics/track {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/track
        header Cache-Control "no-store"
    }
}
```

### Subdomain Proxy [#subdomain-proxy]

Use a dedicated subdomain for analytics:

```txt
# /etc/caddy/Caddyfile

analytics.yourdomain.com {
    reverse_proxy https://app.rybbit.io {
        header_up Host app.rybbit.io
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
    }
    rewrite * /api{uri}
}
```

Then use:

```html
<script src="https://analytics.yourdomain.com/script.js" data-site-id="123"></script>
```

### Request Size Limits [#request-size-limits]

For session replay, increase max body size:

```txt
yourdomain.com {
    # Increase request body limit for session replay
    handle /analytics/session-replay/record/* {
        request_body {
            max_size 10MB
        }
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/session-replay/record{path}
    }
}
```

### Environment-Based Configuration [#environment-based-configuration]

Use Caddy's environment variable support:

```txt
# /etc/caddy/Caddyfile

{$DOMAIN:yourdomain.com} {
    handle_path /analytics/* {
        reverse_proxy {$RYBBIT_HOST:https://app.rybbit.io} {
            header_up Host {upstream_hostport}
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api{uri}
    }
}
```

Then set environment variables:

```bash
export DOMAIN=yourdomain.com
export RYBBIT_HOST=https://app.rybbit.io
caddy run
```

### Rate Limiting [#rate-limiting]

Protect your proxy with rate limiting using the `rate_limit` plugin:

```txt
yourdomain.com {
    handle /analytics/track {
        rate_limit {
            zone analytics {
                key {remote_host}
                events 100
                window 1m
            }
        }
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/track
    }
}
```

<Callout type="warn">
  The `rate_limit` directive requires the [caddy-ratelimit plugin](https://github.com/mholt/caddy-ratelimit). Install with: `xcaddy build --with github.com/mholt/caddy-ratelimit`
</Callout>

## Troubleshooting [#troubleshooting]

### Certificate errors [#certificate-errors]

**Problem**: Caddy fails to obtain SSL certificate.

**Solution**:

1. Verify domain points to your server (DNS)
2. Check ports 80 and 443 are open
3. Ensure no other process is using port 443
4. Check Caddy logs: `journalctl -u caddy -f`

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show same location.

**Solution**:
Ensure you're forwarding client IP:

```txt
reverse_proxy https://app.rybbit.io {
    header_up X-Real-IP {remote_host}
    header_up X-Forwarded-For {remote_host}
}
```

### 502 Bad Gateway [#502-bad-gateway]

**Problem**: Caddy returns 502 when accessing analytics endpoints.

**Solution**:

1. Verify Rybbit backend is accessible:
   ```bash
   curl -I https://app.rybbit.io/api/script.js
   ```
2. Check Caddy logs for errors:
   ```bash
   journalctl -u caddy -n 50
   ```

### Path rewriting not working [#path-rewriting-not-working]

**Problem**: Requests go to wrong Rybbit endpoints.

**Solution**:
Use the `rewrite` directive correctly:

```txt
handle /analytics/script.js {
    rewrite * /api/script.js  # Rewrite before reverse_proxy
    reverse_proxy https://app.rybbit.io {
        # ... headers
    }
}
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Framework-agnostic concepts
* [Caddy Documentation](https://caddyserver.com/docs/) - Official Caddy docs
* [Caddy reverse\_proxy](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) - Reverse proxy directive docs


# Cloudflare Workers Proxy Setup (/de/docs/proxy-guide/cloudflare-workers)





Cloudflare Workers provide a serverless way to proxy Rybbit tracking at the edge, close to your users worldwide. This delivers excellent performance with minimal configuration.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Cloudflare Workers run on Cloudflare's global network, intercepting and proxying requests before they reach your origin server. This makes them perfect for analytics proxying with built-in caching and ultra-low latency.

**What you'll achieve:**

* Edge-based proxying in 300+ cities worldwide
* Automatic caching with Cloudflare's Cache API
* Sub-10ms latency for most requests
* Zero server infrastructure needed

## Prerequisites [#prerequisites]

* Cloudflare account with your domain
* Workers enabled on your account (free tier available)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Create Worker [#create-worker]

  Log in to Cloudflare Dashboard and create a new Worker:

  1. Go to **Workers & Pages** → **Create application** → **Create Worker**
  2. Name it `rybbit-proxy` (or your preferred name)
  3. Click **Deploy** to create the worker

  ### Update Worker Code [#update-worker-code]

  Replace the default code with the proxy implementation:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'With Environment Variables']">
    <Tab>
      ```javascript
      // Cloudflare Worker for Rybbit Analytics Proxy

      const RYBBIT_HOST = 'https://app.rybbit.io';

      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request));
      });

      async function handleRequest(request) {
        const url = new URL(request.url);

        // Only proxy /analytics/* paths
        if (!url.pathname.startsWith('/analytics/')) {
          // Pass through to origin
          return fetch(request);
        }

        try {
          return await proxyToRybbit(request, url);
        } catch (error) {
          console.error('Proxy error:', error);
          return new Response('Analytics proxy error', { status: 500 });
        }
      }

      async function proxyToRybbit(request, url) {
        // Map paths: /analytics/* → /api/*
        let rybbitPath = url.pathname.replace('/analytics/', '/api/');

        // Build Rybbit URL
        const rybbitUrl = new URL(rybbitPath, RYBBIT_HOST);
        rybbitUrl.search = url.search; // Preserve query params

        // Get client IP
        const clientIp = request.headers.get('CF-Connecting-IP') ||
                         request.headers.get('X-Forwarded-For') ||
                         '0.0.0.0';

        // Build request headers
        const proxyHeaders = new Headers(request.headers);
        proxyHeaders.set('X-Real-IP', clientIp);
        proxyHeaders.set('X-Forwarded-For', clientIp);
        proxyHeaders.delete('CF-Connecting-IP'); // Remove Cloudflare internal header

        // Build proxy request
        const proxyRequest = new Request(rybbitUrl, {
          method: request.method,
          headers: proxyHeaders,
          body: request.method !== 'GET' && request.method !== 'HEAD' ? request.body : undefined,
        });

        // Check cache for GET requests
        if (request.method === 'GET') {
          const cache = caches.default;
          let response = await cache.match(proxyRequest);

          if (response) {
            // Return cached response
            return new Response(response.body, {
              status: response.status,
              statusText: response.statusText,
              headers: {
                ...Object.fromEntries(response.headers),
                'X-Cache-Status': 'HIT',
              },
            });
          }
        }

        // Fetch from Rybbit
        const response = await fetch(proxyRequest);

        // Cache scripts for 1 hour
        if (request.method === 'GET' && url.pathname.match(/\.(js)$/)) {
          const cacheResponse = new Response(response.body, response);
          cacheResponse.headers.set('Cache-Control', 'public, max-age=3600');
          cacheResponse.headers.set('X-Cache-Status', 'MISS');

          // Clone and cache
          const cache = caches.default;
          await cache.put(proxyRequest, cacheResponse.clone());

          return cacheResponse;
        }

        // Return non-cacheable response
        return new Response(response.body, {
          status: response.status,
          statusText: response.statusText,
          headers: response.headers,
        });
      }
      ```
    </Tab>

    <Tab>
      ```javascript
      // Minimal Cloudflare Worker for Rybbit

      const RYBBIT_HOST = 'https://app.rybbit.io';

      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request));
      });

      async function handleRequest(request) {
        const url = new URL(request.url);

        // Only proxy /analytics/script.js and /analytics/track
        if (url.pathname === '/analytics/script.js' || url.pathname === '/analytics/track') {
          const rybbitPath = url.pathname.replace('/analytics/', '/api/');
          const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;

          const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

          const proxyHeaders = new Headers(request.headers);
          proxyHeaders.set('X-Real-IP', clientIp);
          proxyHeaders.set('X-Forwarded-For', clientIp);

          return fetch(rybbitUrl, {
            method: request.method,
            headers: proxyHeaders,
            body: request.method === 'POST' ? request.body : undefined,
          });
        }

        // Pass through to origin
        return fetch(request);
      }
      ```
    </Tab>

    <Tab>
      Using Workers secrets for configuration:

      ```javascript
      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request, event.env));
      });

      async function handleRequest(request, env) {
        const RYBBIT_HOST = env.RYBBIT_HOST || 'https://app.rybbit.io';
        const url = new URL(request.url);

        if (!url.pathname.startsWith('/analytics/')) {
          return fetch(request);
        }

        // Map paths: /analytics/* → /api/*
        let rybbitPath = url.pathname.replace('/analytics/', '/api/');

        const rybbitUrl = new URL(rybbitPath, RYBBIT_HOST);
        const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

        const proxyHeaders = new Headers(request.headers);
        proxyHeaders.set('X-Real-IP', clientIp);
        proxyHeaders.set('X-Forwarded-For', clientIp);

        return fetch(rybbitUrl.toString(), {
          method: request.method,
          headers: proxyHeaders,
          body: request.method !== 'GET' ? request.body : undefined,
        });
      }
      ```

      Set environment variable in Cloudflare Dashboard:
      **Workers & Pages** → Your Worker → **Settings** → **Variables** → Add `RYBBIT_HOST`
    </Tab>
  </Tabs>

  ### Deploy Worker [#deploy-worker]

  Click **Save and Deploy** to publish your worker.

  ### Configure Worker Route [#configure-worker-route]

  Set up a route to trigger the worker:

  1. Go to **Workers & Pages** → Your Worker → **Triggers**
  2. Click **Add route**
  3. Configure:
     * **Route**: `yourdomain.com/analytics/*`
     * **Zone**: Select your domain
  4. Click **Save**

  <Callout type="info">
    The route pattern `yourdomain.com/analytics/*` ensures the worker only runs for analytics requests, not your entire site.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Add the script to your website:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Visit your site** with Developer Tools open
  2. **Check Network tab**:
     * Script loads from `/analytics/script.js`
     * Check response headers for `CF-Cache-Status` (HIT/MISS)
  3. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Cloudflare Workers intercept requests at the edge:

1. Request to `yourdomain.com/analytics/script.js` hits Cloudflare edge
2. Worker checks cache for GET requests
3. If not cached, proxies to `app.rybbit.io/api/script.js`
4. Response is cached at the edge location
5. Subsequent requests serve from edge cache (ultra-fast)

All tracking data flows through Cloudflare's network while preserving client IP information.

## Performance Benefits [#performance-benefits]

### Global Edge Network [#global-edge-network]

* **300+ locations worldwide**: Workers run in Cloudflare data centers globally
* **Sub-10ms cold start**: Faster than traditional serverless
* **Automatic scaling**: Handles traffic spikes without configuration

### Built-in Caching [#built-in-caching]

* **Cache API**: Leverages Cloudflare's massive edge cache
* **Intelligent caching**: Scripts cached at edge, tracking requests passed through
* **Instant cache purge**: Clear cache via Cloudflare API if needed

### Zero Infrastructure [#zero-infrastructure]

* **No servers to manage**: Fully serverless
* **Pay-per-request**: Free tier includes 100,000 requests/day
* **Automatic HTTPS**: Cloudflare handles SSL

## Advanced Configuration [#advanced-configuration]

### Cache Control [#cache-control]

Customize caching behavior:

```javascript
// Cache scripts for different durations
if (url.pathname === '/analytics/script.js') {
  cacheResponse.headers.set('Cache-Control', 'public, max-age=3600'); // 1 hour
} else if (url.pathname === '/analytics/replay.js') {
  cacheResponse.headers.set('Cache-Control', 'public, max-age=7200'); // 2 hours
}
```

### Rate Limiting [#rate-limiting]

Add basic rate limiting:

```javascript
// Simple in-memory rate limiting (per edge location)
const rateLimitMap = new Map();

async function checkRateLimit(ip) {
  const key = `ratelimit:${ip}`;
  const current = rateLimitMap.get(key) || { count: 0, resetAt: Date.now() + 60000 };

  if (Date.now() > current.resetAt) {
    current.count = 0;
    current.resetAt = Date.now() + 60000;
  }

  current.count++;
  rateLimitMap.set(key, current);

  return current.count > 100; // 100 requests per minute
}
```

### Logging and Analytics [#logging-and-analytics]

Log proxy usage:

```javascript
async function handleRequest(request) {
  const startTime = Date.now();

  try {
    const response = await proxyToRybbit(request, url);
    const duration = Date.now() - startTime;

    // Log to Cloudflare Analytics Engine (if enabled)
    console.log({
      path: url.pathname,
      status: response.status,
      duration,
      cached: response.headers.get('X-Cache-Status') === 'HIT',
    });

    return response;
  } catch (error) {
    console.error('Proxy error:', error);
    return new Response('Error', { status: 500 });
  }
}
```

## Cost Considerations [#cost-considerations]

Cloudflare Workers pricing (as of 2024):

* **Free tier**: 100,000 requests/day
* **Paid plan**: $5/month for 10 million requests + $0.50 per million after

For typical traffic:

* 100,000 sessions/month ≈ 200,000-500,000 requests (well within free tier)
* Even with session replay: Usually under 1 million requests/month

<Callout type="info">
  Most sites stay within the free tier. Bandwidth is unlimited on all Cloudflare plans.
</Callout>

## Troubleshooting [#troubleshooting]

### Worker not triggering [#worker-not-triggering]

**Problem**: Requests bypass worker.

**Solution**:

1. Verify route is configured: `yourdomain.com/analytics/*`
2. Check zone matches your domain
3. Ensure orange-cloud (proxy) is enabled on DNS record

### Cache not working [#cache-not-working]

**Problem**: `X-Cache-Status` always shows MISS.

**Solution**:

1. Verify cache key includes important parts:
   ```javascript
   const cacheKey = new Request(rybbitUrl, request);
   ```
2. Ensure `Cache-Control` headers are set
3. Check method is GET (POST requests aren't cached)

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show Cloudflare IPs.

**Solution**:
Use `CF-Connecting-IP` header:

```javascript
const clientIp = request.headers.get('CF-Connecting-IP');
proxyHeaders.set('X-Real-IP', clientIp);
```

### Deployment errors [#deployment-errors]

**Problem**: Worker fails to deploy.

**Solution**:

1. Check syntax in editor (no console.log in production)
2. Verify all async functions use await
3. Test locally with Wrangler:
   ```bash
   npm install -g wrangler
   wrangler dev
   ```

## Local Development [#local-development]

Use Wrangler for local testing:

```bash
# Install Wrangler
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Create worker
wrangler init rybbit-proxy

# Dev server
wrangler dev

# Deploy
wrangler deploy
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/) - Official docs
* [Workers Cache API](https://developers.cloudflare.com/workers/runtime-apis/cache/) - Caching documentation


# Express.js Proxy Setup (/de/docs/proxy-guide/express)





Express.js makes it easy to proxy Rybbit tracking using middleware. This guide shows how to set up a reverse proxy using `http-proxy-middleware`.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

The `http-proxy-middleware` package provides a simple way to proxy requests in Express applications, making it perfect for routing analytics requests to Rybbit servers.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your Express app
* Forward necessary headers for accurate tracking
* Optional caching for better performance
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Node.js and Express.js application
* npm or yarn package manager
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Install http-proxy-middleware [#install-http-proxy-middleware]

  Install the proxy middleware package:

  ```bash
  npm install http-proxy-middleware
  ```

  Or with yarn:

  ```bash
  yarn add http-proxy-middleware
  ```

  ### Configure Environment Variables [#configure-environment-variables]

  Create or update your `.env` file:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  <Callout type="info">
    Install `dotenv` if not already: `npm install dotenv`
  </Callout>

  ### Add Proxy Middleware to Express [#add-proxy-middleware-to-express]

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'TypeScript']">
    <Tab>
      Add to your Express server file (e.g., `server.js` or `app.js`):

      ```javascript
      // server.js
      require('dotenv').config();
      const express = require('express');
      const { createProxyMiddleware } = require('http-proxy-middleware');

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      // Rybbit Analytics Proxy
      // Proxy all /analytics/* requests to Rybbit
      app.use('/analytics', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api', // Rewrite /analytics/script.js to /api/script.js
        },
        onProxyReq: (proxyReq, req, res) => {
          // Forward client IP for accurate geolocation
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
        logLevel: 'warn',
      }));

      // Exception for site config endpoint (different path structure)
      app.use('/analytics/site/tracking-config', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics/site': '/api/site', // Rewrite to /api/site/tracking-config
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
      }));

      // Your other routes
      app.get('/', (req, res) => {
        res.send('Hello World');
      });

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>

    <Tab>
      Minimal setup with basic tracking:

      ```javascript
      // server.js
      require('dotenv').config();
      const express = require('express');
      const { createProxyMiddleware } = require('http-proxy-middleware');

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      // Proxy script and track endpoints only
      app.use(['/analytics/script.js', '/analytics/track'], createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api',
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
      }));

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>

    <Tab>
      For TypeScript projects:

      ```typescript
      // server.ts
      import 'dotenv/config';
      import express, { Request, Response } from 'express';
      import { createProxyMiddleware, Options } from 'http-proxy-middleware';

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      const proxyOptions: Options = {
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api',
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp as string);
          proxyReq.setHeader('X-Real-IP', clientIp as string);
        },
        logLevel: 'warn',
      };

      app.use('/analytics', createProxyMiddleware(proxyOptions));

      app.use('/analytics/site/tracking-config', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics/site': '/api/site',
        },
        onProxyReq: proxyOptions.onProxyReq,
      }));

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>
  </Tabs>

  ### Update Your Tracking Script [#update-your-tracking-script]

  In your HTML or template files:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Start Your Server [#start-your-server]

  ```bash
  node server.js
  ```

  Or with nodemon for development:

  ```bash
  npm install -D nodemon
  npx nodemon server.js
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Test script endpoint**:
     ```bash
     curl -I http://localhost:3000/analytics/script.js
     ```

  2. **Open your app** in a browser with Developer Tools

  3. **Check Network tab**: Requests should go to `/analytics/*`

  4. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

The `http-proxy-middleware` intercepts requests matching the specified paths and forwards them to Rybbit:

1. Request to `/analytics/script.js` is intercepted
2. Path is rewritten to `/api/script.js`
3. Request is forwarded to `https://app.rybbit.io/api/script.js`
4. Client IP headers are added for accurate tracking
5. Response is sent back to the browser

## Advanced Configuration [#advanced-configuration]

### Caching Responses [#caching-responses]

Add caching for better performance:

```javascript
const NodeCache = require('node-cache');
const cache = new NodeCache({ stdTTL: 3600 }); // 1 hour default

// Install: npm install node-cache

// Caching middleware for scripts
const cacheMiddleware = (req, res, next) => {
  const key = req.originalUrl;
  const cachedResponse = cache.get(key);

  if (cachedResponse) {
    res.set('X-Cache-Status', 'HIT');
    return res.send(cachedResponse);
  }

  // Store original send
  const originalSend = res.send.bind(res);
  res.send = (body) => {
    cache.set(key, body);
    res.set('X-Cache-Status', 'MISS');
    return originalSend(body);
  };
  next();
};

// Apply caching only to script files
app.use('/analytics/script.js', cacheMiddleware);
app.use('/analytics/script.js', createProxyMiddleware({
  // ... proxy config
}));
```

### Request Size Limits [#request-size-limits]

For session replay uploads, increase body size limit:

```javascript
const express = require('express');
const app = express();

// Increase limit for session replay endpoints
app.use('/analytics/session-replay', express.json({ limit: '10mb' }));
app.use('/analytics/session-replay', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  pathRewrite: {
    '^/analytics': '/api',
  },
}));
```

### Rate Limiting [#rate-limiting]

Protect your proxy with rate limiting:

```javascript
const rateLimit = require('express-rate-limit');

// Install: npm install express-rate-limit

const analyticsLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 100, // Limit each IP to 100 requests per minute
  message: 'Too many requests from this IP',
  standardHeaders: true,
  legacyHeaders: false,
});

// Apply to tracking endpoints
app.use('/analytics/track', analyticsLimiter);
app.use('/analytics/track', createProxyMiddleware({
  // ... proxy config
}));
```

### Error Handling [#error-handling]

Add error handling for proxy failures:

```javascript
app.use('/analytics', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  pathRewrite: {
    '^/analytics': '/api',
  },
  onError: (err, req, res) => {
    console.error('Proxy error:', err);
    res.status(500).json({ error: 'Analytics proxy error' });
  },
  onProxyReq: (proxyReq, req, res) => {
    const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
    proxyReq.setHeader('X-Forwarded-For', clientIp);
    proxyReq.setHeader('X-Real-IP', clientIp);
  },
}));
```

### CORS Configuration [#cors-configuration]

If serving API endpoints to other domains:

```javascript
const cors = require('cors');

// Install: npm install cors

app.use('/analytics', cors({
  origin: ['https://yourdomain.com', 'https://www.yourdomain.com'],
  credentials: true,
}));

app.use('/analytics', createProxyMiddleware({
  // ... proxy config
}));
```

## Troubleshooting [#troubleshooting]

### Requests timing out [#requests-timing-out]

**Problem**: Proxy requests hang or timeout.

**Solution**:
Increase timeout limits:

```javascript
app.use('/analytics', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  timeout: 30000, // 30 seconds
  proxyTimeout: 30000,
  pathRewrite: {
    '^/analytics': '/api',
  },
}));
```

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show server's location.

**Solution**:
Ensure IP forwarding is configured:

```javascript
onProxyReq: (proxyReq, req, res) => {
  const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  proxyReq.setHeader('X-Forwarded-For', clientIp);
  proxyReq.setHeader('X-Real-IP', clientIp);
}
```

### Path rewriting issues [#path-rewriting-issues]

**Problem**: 404 errors on Rybbit endpoints.

**Solution**:
Check path rewriting is correct:

```javascript
pathRewrite: {
  '^/analytics': '/api', // /analytics/script.js → /api/script.js
}
```

Debug by logging:

```javascript
onProxyReq: (proxyReq, req, res) => {
  console.log('Proxying:', req.method, req.path, '→', proxyReq.path);
}
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [http-proxy-middleware docs](https://github.com/chimurai/http-proxy-middleware) - Middleware documentation


# Generic Proxy Setup (/de/docs/proxy-guide/get-started)





This guide covers the core concepts for setting up a Rybbit proxy with any reverse proxy or server framework. If your specific framework has a dedicated guide, we recommend following that instead for optimized instructions.

## Prerequisites [#prerequisites]

Before setting up the proxy, ensure you have:

* **A domain or subdomain** where you'll serve the proxied scripts (e.g., `yourdomain.com` or `analytics.yourdomain.com`)
* **SSL/TLS certificate** for HTTPS (required for modern browsers)
* **Server or platform** with reverse proxy capabilities
* **Your Rybbit instance URL**:
  * Cloud: `https://app.rybbit.io`
  * Self-hosted: Your Rybbit instance URL (e.g., `https://analytics.yourcompany.com`)
* **Your Rybbit site ID** (found in your Rybbit dashboard)

## Understanding the Endpoints [#understanding-the-endpoints]

Rybbit uses several endpoints for tracking. You can choose between a minimal setup or full proxy:

<Tabs items="['Minimal Setup', 'Full Setup (Recommended)']">
  <Tab>
    **Required endpoints for basic tracking:**

    | Endpoint         | Method | Purpose                 | Cache    |
    | ---------------- | ------ | ----------------------- | -------- |
    | `/api/script.js` | GET    | Main tracking script    | 1 hour   |
    | `/api/track`     | POST   | Event tracking endpoint | No cache |

    This minimal setup enables basic pageview and event tracking, but won't support session replay or some advanced features.
  </Tab>

  <Tab>
    **All endpoints for complete functionality:**

    | Endpoint                             | Method | Purpose                         | Cache     |
    | ------------------------------------ | ------ | ------------------------------- | --------- |
    | `/api/script.js`                     | GET    | Main tracking script (minified) | 1 hour    |
    | `/api/replay.js`                     | GET    | Session replay recording script | 1 day     |
    | `/api/metrics.js`                    | GET    | Web Vitals metrics script       | 1 day     |
    | `/api/track`                         | POST   | Event tracking endpoint         | No cache  |
    | `/api/identify`                      | POST   | User identification endpoint    | No cache  |
    | `/api/session-replay/record/:siteId` | POST   | Session replay data upload      | No cache  |
    | `/api/site/tracking-config/:siteId`  | GET    | Site configuration              | 5 minutes |

    This setup supports all Rybbit features including session replay, Web Vitals, and custom events.
  </Tab>
</Tabs>

<Callout type="info">
  The session replay and metrics scripts (`/api/replay.js` and `/api/metrics.js`) are loaded dynamically by the main script when those features are enabled in your site settings. You don't need to include them in your HTML.
</Callout>

## Implementation Steps [#implementation-steps]

<Steps>
  ### Configure Your Proxy Rules [#configure-your-proxy-rules]

  Set up your reverse proxy to forward requests from your chosen path (e.g., `/analytics/*`) to the Rybbit server.

  **Generic proxy configuration pattern:**

  ```
  Your domain path          →  Rybbit backend
  -----------------            ---------------
  /analytics/script.js      →  https://app.rybbit.io/api/script.js
  /analytics/track          →  https://app.rybbit.io/api/track
  /analytics/replay.js      →  https://app.rybbit.io/api/replay.js
  ... and so on
  ```

  **Key requirements:**

  * Preserve the HTTP method (GET or POST)
  * Forward the browser's original request headers — pass through **all** incoming headers except `Host` and hop-by-hop headers (`Connection`, `Content-Length`), rather than hand-picking a few. See [Request Header Forwarding](#request-header-forwarding) for why this matters.
  * Maintain request/response body for POST requests
  * Set appropriate Content-Type headers
  * Forward the visitor IP in `X-Forwarded-For`
  * Enable the **First-Party Proxy** toggle for your site (see below)

  ### Enable First-Party Proxy in Site Settings [#enable-first-party-proxy-in-site-settings]

  In your Rybbit dashboard, open **Site Settings → Privacy & Security** and enable **First-Party Proxy**. This tells Rybbit that requests for this site arrive via your proxy, so the visitor IP in `X-Forwarded-For` is trusted directly instead of being inferred from network topology. Without it, Rybbit may attribute traffic to your proxy server's IP — producing wrong geolocation and merging all visitors into a few users.

  ### Configure Caching (Optional but Recommended) [#configure-caching-optional-but-recommended]

  Implement caching to reduce load on Rybbit servers and improve performance:

  **Recommended cache durations:**

  * **Scripts** (`.js` files): 1 hour (3600 seconds)
    * These change infrequently but may be updated for bug fixes
  * **Site configuration** (`/api/site/tracking-config/*`): 5 minutes (300 seconds)
    * Updated when you change settings in the dashboard
  * **Tracking endpoints** (POST requests): Never cache
    * Each request contains unique event data

  **Example cache headers to set:**

  ```
  Cache-Control: public, max-age=3600  # For scripts
  Cache-Control: public, max-age=300   # For config
  Cache-Control: no-store              # For tracking POSTs
  ```

  ### Update Your Tracking Script [#update-your-tracking-script]

  Change your script tag to load from your proxied domain instead of directly from Rybbit:

  **Before (direct loading):**

  ```html
  <script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  **After (proxied):**

  ```html
  <script src="https://yourdomain.com/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  <Callout type="info">
    **How Auto-Discovery Works**: The Rybbit script automatically extracts the analytics host from its own `src` attribute by splitting on `/script.js`. This means when it loads from `https://yourdomain.com/analytics/script.js`, it automatically sends all tracking data to `https://yourdomain.com/analytics/*` endpoints.
  </Callout>

  ### Verify the Setup [#verify-the-setup]

  Test your proxy configuration to ensure everything works correctly:

  1. **Open your website** in a browser with Developer Tools open
  2. **Go to the Network tab** and filter by "script" or your proxy path
  3. **Verify the script loads**:
     * You should see a request to `yourdomain.com/analytics/script.js`
     * Status should be `200 OK`
     * Content-Type should be `application/javascript`
  4. **Verify tracking works**:
     * Navigate to another page or trigger an event
     * You should see POST requests to `yourdomain.com/analytics/track`
     * Check the response is successful (200 OK)
  5. **Check your Rybbit dashboard**:
     * Wait 1-2 minutes for data to process
     * Verify your session appears in real-time dashboard

  ### Configure Security Headers (Optional) [#configure-security-headers-optional]

  Add security headers to protect your proxy:

  **Recommended headers:**

  ```
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  Referrer-Policy: strict-origin-when-cross-origin
  ```

  **CORS headers** (should be preserved from Rybbit):

  ```
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, OPTIONS
  Access-Control-Allow-Headers: Content-Type
  ```
</Steps>

## Request Header Forwarding [#request-header-forwarding]

Forward the browser's original headers to the Rybbit backend. The simplest and most robust approach is to pass through **every** incoming request header except `Host` and hop-by-hop headers (`Connection`, `Content-Length` — let your HTTP client recompute those).

Why this matters: Rybbit's bot detection scores requests on headers that every real browser sends. A proxy that forwards only `User-Agent` and the visitor IP produces requests that look exactly like a script — the events return `200 OK` but are classified as bot traffic and never appear in your dashboard.

If you must whitelist headers instead of passing everything through, this is the minimum set:

| Header                                                | Purpose                                            | Required    |
| ----------------------------------------------------- | -------------------------------------------------- | ----------- |
| `User-Agent`                                          | Device and browser detection                       | Yes         |
| `X-Forwarded-For`                                     | Visitor IP for geolocation and user identification | Yes         |
| `Accept-Language`                                     | Language detection, bot filtering                  | Yes         |
| `Accept`                                              | Bot filtering                                      | Yes         |
| `Accept-Encoding`                                     | Bot filtering (must include `gzip`)                | Yes         |
| `Sec-Fetch-Site`, `Sec-Fetch-Mode`, `Sec-Fetch-Dest`  | Bot filtering (sent by all Chromium browsers)      | Yes         |
| `Sec-CH-UA`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Platform` | Browser detection                                  | Recommended |
| `Referer`                                             | Referrer tracking                                  | Recommended |
| `Content-Type`                                        | POST body parsing                                  | Yes (POSTs) |

<Callout type="warn">
  **IP Forwarding**: Rybbit uses IP addresses for geolocation (country/city) and creating anonymous user identifiers (hashed IP + User Agent). If you don't forward the visitor IP in `X-Forwarded-For`, all traffic will appear to come from your proxy server's IP.
</Callout>

### Forwarded IP Headers [#forwarded-ip-headers]

Set `X-Forwarded-For` to the original visitor IP before forwarding the request to Rybbit, and enable the **First-Party Proxy** toggle in your site settings so Rybbit trusts it unconditionally.

<Callout type="warn">
  **Use `X-Forwarded-For`, not `X-Real-IP`.** On Rybbit Cloud, `X-Real-IP` is consumed by our edge network (Cloudflare treats it as an internal header) and never reaches the backend — a proxy that relies on it will silently fall back to the wrong IP. `X-Forwarded-For` passes through intact. Coincidentally, AWS CloudFront also cannot send `X-Real-IP` (it's on the [origin custom-header denylist](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html#add-origin-custom-headers-denylist)). Setting `X-Real-IP` as well does no harm on self-hosted instances, but never make it the only IP header.
</Callout>

**Cloudflare Worker example:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

const proxyHeaders = new Headers(request.headers);
proxyHeaders.set('X-Real-IP', clientIp);
proxyHeaders.set('X-Forwarded-For', clientIp);
```

**CloudFront example:**

* Set `X-Forwarded-For` to the viewer IP from a CloudFront Function/Lambda\@Edge (CloudFront cannot forward `X-Real-IP`)
* Forward `User-Agent`, `Referer`, and `Accept-Language`

```javascript
// CloudFront Function (viewer-request)
function handler(event) {
  event.request.headers["x-forwarded-for"] = { value: event.viewer.ip };
  return event.request;
}
```

## Bandwidth Considerations [#bandwidth-considerations]

Proxying adds bandwidth usage to your infrastructure. Here's what to expect:

**Typical bandwidth per session:**

* Initial script load: \~18 KB (one-time per session)
* Pageview tracking: \~0.5-2 KB per pageview
* Custom events: \~0.5-3 KB per event
* Session replay: 50-500 KB per session (if enabled, varies by session length)
* Web Vitals: \~1-2 KB per page

**Estimated monthly bandwidth** for a site with 100,000 monthly sessions:

* Without session replay: \~5-10 GB/month
* With session replay: \~30-80 GB/month

Most modern hosting plans can handle this easily, but verify your bandwidth limits if you have high traffic or session replay enabled.

## Performance Optimization [#performance-optimization]

### Use a CDN [#use-a-cdn]

If your server has CDN capabilities (like Cloudflare, Fastly, or AWS CloudFront), configure it to cache the static scripts:

* Cache scripts at edge locations worldwide
* Reduce latency for global users
* Offload bandwidth from your origin server

### Enable Compression [#enable-compression]

Ensure your proxy enables gzip or brotli compression:

```
Content-Encoding: gzip
```

This can reduce script size by 60-70%, improving load times and reducing bandwidth.

### Connection Reuse [#connection-reuse]

Configure your proxy to maintain persistent connections to Rybbit's backend to reduce latency on repeated requests.

## Common Proxy Patterns [#common-proxy-patterns]

<Tabs items="['Subdomain Proxy', 'Path-Based Proxy']">
  <Tab>
    Use a dedicated subdomain for analytics:

    ```
    https://analytics.yourdomain.com/script.js  →  https://app.rybbit.io/api/script.js
    https://analytics.yourdomain.com/track      →  https://app.rybbit.io/api/track
    ```

    **Pros:**

    * Clean separation of concerns
    * Easy to manage SSL certificate
    * Can use separate CDN configuration

    **Cons:**

    * Additional DNS lookup (minor performance impact)
    * Need to manage subdomain DNS
  </Tab>

  <Tab>
    Use a path on your main domain:

    ```
    https://yourdomain.com/analytics/script.js  →  https://app.rybbit.io/api/script.js
    https://yourdomain.com/analytics/track      →  https://app.rybbit.io/api/track
    ```

    **Pros:**

    * No additional DNS lookup
    * Single SSL certificate
    * Truly first-party from browser perspective

    **Cons:**

    * Must ensure proxy path doesn't conflict with your app routes
  </Tab>
</Tabs>

## Security Considerations [#security-considerations]

### Rate Limiting [#rate-limiting]

Consider adding rate limiting to prevent abuse:

* Limit POST requests to tracking endpoints (e.g., 100 requests per minute per IP)
* Whitelist your Rybbit backend IP if possible
* Monitor for unusual traffic patterns

### Request Size Limits [#request-size-limits]

Set appropriate request body size limits:

* `/api/track`, `/api/identify`: 1 MB max
* `/api/session-replay/record/*`: 10 MB max (session replay can send large payloads)

### HTTPS Only [#https-only]

Always serve your proxy over HTTPS:

* Modern browsers require HTTPS for many features
* Protects user data in transit
* Required for accurate tracking in secure contexts

## Troubleshooting [#troubleshooting]

If something isn't working, check:

1. **Script loads but no events tracked**: Verify all tracking endpoints (`/api/track`, etc.) are proxied
2. **CORS errors**: Ensure CORS headers are preserved from Rybbit backend
3. **404 errors**: Check that URL paths exactly match expected format
4. **Incorrect geolocation**: Verify `X-Forwarded-For` is set to the visitor IP and the **First-Party Proxy** toggle is enabled in site settings
5. **`/track` returns 200 but nothing appears in the dashboard**: Your proxy is probably forwarding too few headers and events are being classified as bot traffic — forward the full browser header set (see [Request Header Forwarding](#request-header-forwarding))
6. **Session replay not working**: Add `/api/replay.js` and `/api/session-replay/record/:siteId` endpoints

For more detailed troubleshooting, see our [troubleshooting guide](/docs/proxy-guide/troubleshooting).

## Next Steps [#next-steps]

Now that you understand the generic concepts, choose your specific framework or platform for detailed implementation instructions:

* [Next.js](/docs/proxy-guide/next-js)
* [Nginx](/docs/proxy-guide/nginx)
* [Caddy](/docs/proxy-guide/caddy)
* [Vercel](/docs/proxy-guide/vercel)
* [Express.js](/docs/proxy-guide/express)
* [Laravel](/docs/proxy-guide/laravel)
* [Astro](/docs/proxy-guide/astro)
* [Cloudflare Workers](/docs/proxy-guide/cloudflare-workers)


# Proxy Setup Guide (/de/docs/proxy-guide)





Proxying Rybbit's tracking script through your own domain helps bypass ad blockers and improves tracking accuracy by making all analytics requests appear as first-party traffic.

## What is Proxy Setup? [#what-is-proxy-setup]

When you add Rybbit's tracking script directly to your website using the default installation:

```html
<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
```

The browser loads the script from `app.rybbit.io`, which ad blockers can identify and block as third-party analytics. Even though Rybbit is privacy-focused and doesn't use cookies, some ad blockers use aggressive blocking rules that target any analytics domains.

**Proxying solves this** by serving the tracking script and handling tracking requests through your own domain (e.g., `yourdomain.com/analytics/script.js`), making all tracking appear as first-party traffic.

<Callout type="info">
  Rybbit is fully compliant with GDPR, CCPA, and other privacy regulations. It uses cookieless tracking based on IP + User Agent hashing with optional daily rotating salts. Proxying is about improving data accuracy, not circumventing privacy laws.
</Callout>

## Why Proxy Rybbit? [#why-proxy-rybbit]

### Improve Tracking Accuracy [#improve-tracking-accuracy]

Ad blockers are becoming increasingly aggressive and may block analytics scripts regardless of their privacy practices. By proxying through your own domain:

* **Bypass ad blocker detection**: Requests appear as first-party traffic to your own domain
* **Increase data completeness**: Typical improvement of 10-30% in tracked sessions
* **Maintain accurate metrics**: Get a true picture of your website's performance

### Stay Privacy-Compliant [#stay-privacy-compliant]

Proxying doesn't compromise user privacy:

* No cookies are used (Rybbit remains cookieless)
* User data is still processed according to your privacy policy
* GDPR, CCPA, and other privacy regulations remain fully satisfied
* Users can still opt out through browser settings or Do Not Track

### Better Performance (Optional) [#better-performance-optional]

With proper caching configuration, proxying can also improve performance:

* Serve scripts from your CDN or edge network
* Reduce DNS lookups (one less domain to resolve)
* Cache static scripts closer to your users

## How It Works [#how-it-works]

Here's the flow when you proxy Rybbit:

1. **User visits your website**: Your HTML includes the tracking script from your domain
   ```html
   <script src="https://yourdomain.com/analytics/script.js" data-site-id="123"></script>
   ```

2. **Script loads from your domain**: Your server proxies the request to Rybbit's servers
   * Request: `yourdomain.com/analytics/script.js` → proxied to → `app.rybbit.io/api/script.js`

3. **Script auto-discovers analytics host**: The Rybbit script automatically detects the domain it was loaded from
   ```typescript
   // The script extracts the host from its own src attribute
   const analyticsHost = src.split("/script.js")[0];
   // Result: "https://yourdomain.com/analytics"
   ```

4. **Tracking data sent through your domain**: All analytics events are sent to your domain and proxied to Rybbit
   * Event tracking: `yourdomain.com/analytics/track` → proxied to → `app.rybbit.io/api/track`
   * Session replay: `yourdomain.com/analytics/session-replay/record/{siteId}` → proxied
   * Configuration: `yourdomain.com/analytics/site/tracking-config/{siteId}` → proxied

5. **Data appears in your Rybbit dashboard**: No changes needed in the Rybbit interface

<Callout type="warn">
  **Bandwidth Consideration**: All tracking requests will flow through your server infrastructure, which will increase bandwidth usage. For most sites this is minimal (typically 10-50KB per session), but consider this when evaluating hosting costs.
</Callout>

## Choose Your Framework [#choose-your-framework]

Select the framework or platform that matches your setup:

<Cards>
  <Card icon="<SiNextdotjs />" title="Next.js" href="/docs/proxy-guide/next-js" className="flex items-center gap-2" />

  <Card icon="<SiNginx />" title="Nginx" href="/docs/proxy-guide/nginx" className="flex items-center gap-2" />

  <Card title="Caddy" href="/docs/proxy-guide/caddy" className="flex items-center gap-2" />

  <Card icon="<SiVercel />" title="Vercel" href="/docs/proxy-guide/vercel" className="flex items-center gap-2" />

  <Card icon="<SiExpress />" title="Express.js" href="/docs/proxy-guide/express" className="flex items-center gap-2" />

  <Card icon="<SiLaravel />" title="Laravel" href="/docs/proxy-guide/laravel" className="flex items-center gap-2" />

  <Card icon="<SiAstro />" title="Astro" href="/docs/proxy-guide/astro" className="flex items-center gap-2" />

  <Card icon="<SiCloudflare />" title="Cloudflare Workers" href="/docs/proxy-guide/cloudflare-workers" className="flex items-center gap-2" />
</Cards>

## Generic Implementation [#generic-implementation]

If your framework isn't listed above, check out our [generic implementation guide](/docs/proxy-guide/get-started) that covers the core concepts applicable to any reverse proxy or server setup.

## Need Help? [#need-help]

If you encounter issues during setup, check our [troubleshooting guide](/docs/proxy-guide/troubleshooting) for common problems and solutions.


# Laravel Proxy Setup (/de/docs/proxy-guide/laravel)





Laravel makes it straightforward to proxy Rybbit tracking using routes and the HTTP client. This guide shows how to set up proxy endpoints in your Laravel application.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Laravel's HTTP client (built on Guzzle) provides an elegant way to proxy requests to Rybbit servers while maintaining full control over headers, caching, and error handling.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your Laravel app
* Forward necessary headers for accurate tracking
* Optional caching with Laravel Cache
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Laravel 8 or later
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Configure Environment Variables [#configure-environment-variables]

  Add your Rybbit host to `.env`:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  ### Create Analytics Controller [#create-analytics-controller]

  Generate a controller for handling analytics proxying:

  ```bash
  php artisan make:controller AnalyticsProxyController
  ```

  Then implement the proxy logic:

  ```php
  <?php
  // app/Http/Controllers/AnalyticsProxyController.php

  namespace App\Http\Controllers;

  use Illuminate\Http\Request;
  use Illuminate\Support\Facades\Http;
  use Illuminate\Support\Facades\Cache;

  class AnalyticsProxyController extends Controller
  {
      private string $rybbitHost;

      public function __construct()
      {
          $this->rybbitHost = config('services.rybbit.host', 'https://app.rybbit.io');
      }

      /**
       * Proxy script requests (GET)
       */
      public function proxyScript(Request $request, string $script)
      {
          // Cache scripts for 1 hour
          $cacheKey = "rybbit_script_{$script}";

          return Cache::remember($cacheKey, 3600, function () use ($script, $request) {
              return $this->forwardRequest("api/{$script}", 'GET', $request);
          });
      }

      /**
       * Proxy tracking requests (POST)
       */
      public function proxyTrack(Request $request)
      {
          return $this->forwardRequest('api/track', 'POST', $request);
      }

      /**
       * Proxy identify requests (POST)
       */
      public function proxyIdentify(Request $request)
      {
          return $this->forwardRequest('api/identify', 'POST', $request);
      }

      /**
       * Proxy session replay recording (POST)
       */
      public function proxySessionReplay(Request $request, string $siteId)
      {
          return $this->forwardRequest("api/session-replay/record/{$siteId}", 'POST', $request);
      }

      /**
       * Proxy site configuration (GET)
       */
      public function proxySiteConfig(Request $request, string $siteId)
      {
          // Cache config for 5 minutes
          $cacheKey = "rybbit_config_{$siteId}";

          return Cache::remember($cacheKey, 300, function () use ($siteId, $request) {
              return $this->forwardRequest("api/site/tracking-config/{$siteId}", 'GET', $request);
          });
      }

      /**
       * Forward request to Rybbit backend
       */
      private function forwardRequest(string $path, string $method, Request $request)
      {
          $url = "{$this->rybbitHost}/{$path}";

          // Get client IP
          $clientIp = $request->header('X-Forwarded-For', $request->ip());

          // Build HTTP request
          $httpRequest = Http::timeout(30)
              ->withHeaders([
                  'X-Real-IP' => $clientIp,
                  'X-Forwarded-For' => $clientIp,
                  'User-Agent' => $request->header('User-Agent'),
                  'Referer' => $request->header('Referer', ''),
              ]);

          try {
              if ($method === 'POST') {
                  $response = $httpRequest->post($url, $request->all());
              } else {
                  $response = $httpRequest->get($url);
              }

              return response($response->body(), $response->status())
                  ->header('Content-Type', $response->header('Content-Type'));
          } catch (\Exception $e) {
              \Log::error('Rybbit proxy error', [
                  'url' => $url,
                  'error' => $e->getMessage(),
              ]);

              return response()->json(['error' => 'Analytics proxy error'], 500);
          }
      }
  }
  ```

  ### Add Routes [#add-routes]

  Add routes for the analytics proxy in `routes/web.php`:

  ```php
  <?php
  // routes/web.php

  use App\Http\Controllers\AnalyticsProxyController;

  // Analytics proxy routes
  Route::prefix('analytics')->group(function () {
      // Scripts (GET)
      Route::get('/{script}', [AnalyticsProxyController::class, 'proxyScript'])
          ->where('script', '(script|replay|metrics)\.js');

      // Tracking endpoints (POST)
      Route::post('/track', [AnalyticsProxyController::class, 'proxyTrack']);
      Route::post('/identify', [AnalyticsProxyController::class, 'proxyIdentify']);
      Route::post('/session-replay/record/{siteId}', [AnalyticsProxyController::class, 'proxySessionReplay']);

      // Configuration (GET)
      Route::get('/site/tracking-config/{siteId}', [AnalyticsProxyController::class, 'proxySiteConfig']);
  });
  ```

  ### Add Service Configuration (Optional) [#add-service-configuration-optional]

  Add Rybbit configuration to `config/services.php`:

  ```php
  <?php
  // config/services.php

  return [
      // ... other services

      'rybbit' => [
          'host' => env('RYBBIT_HOST', 'https://app.rybbit.io'),
      ],
  ];
  ```

  ### Update Your Blade Templates [#update-your-blade-templates]

  Add the tracking script to your layout:

  ```blade
  {{-- resources/views/layouts/app.blade.php --}}
  <!DOCTYPE html>
  <html lang="en">
  <head>
      <meta charset="UTF-8">
      <title>{{ config('app.name') }}</title>

      {{-- Rybbit Analytics --}}
      <script src="{{ url('/analytics/script.js') }}" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      @yield('content')
  </body>
  </html>
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Clear route cache** (if caching enabled):
     ```bash
     php artisan route:clear
     ```

  2. **Visit your application** with Developer Tools open

  3. **Check Network tab**: Requests should go to `/analytics/*`

  4. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Laravel routes intercept requests to `/analytics/*` and forward them to Rybbit:

1. Request to `/analytics/script.js` hits Laravel route
2. Controller forwards to `https://app.rybbit.io/api/script.js`
3. Response is cached (for cacheable endpoints)
4. Client IP and headers are preserved for accurate tracking

## Advanced Configuration [#advanced-configuration]

### Middleware for Rate Limiting [#middleware-for-rate-limiting]

Create rate limiting middleware:

```bash
php artisan make:middleware RateLimitAnalytics
```

```php
<?php
// app/Http/Middleware/RateLimitAnalytics.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Cache\RateLimiter;

class RateLimitAnalytics
{
    protected $limiter;

    public function __construct(RateLimiter $limiter)
    {
        $this->limiter = $limiter;
    }

    public function handle($request, Closure $next)
    {
        $key = 'analytics:' . $request->ip();

        if ($this->limiter->tooManyAttempts($key, 100)) {
            return response('Too Many Requests', 429);
        }

        $this->limiter->hit($key, 60); // 100 requests per minute

        return $next($request);
    }
}
```

Register in `app/Http/Kernel.php`:

```php
protected $routeMiddleware = [
    // ... other middleware
    'rate.limit.analytics' => \App\Http\Middleware\RateLimitAnalytics::class,
];
```

Apply to routes:

```php
Route::prefix('analytics')->middleware('rate.limit.analytics')->group(function () {
    // ... routes
});
```

### Custom Cache Configuration [#custom-cache-configuration]

Use different cache drivers for analytics:

```php
private function forwardRequest(string $path, string $method, Request $request)
{
    // Use Redis for analytics caching
    $cache = Cache::store('redis');

    // Or use file cache
    // $cache = Cache::store('file');

    // ... rest of the method
}
```

### Queue Large Requests [#queue-large-requests]

For large session replay uploads, use queues:

```bash
php artisan make:job ForwardAnalyticsData
```

```php
<?php
// app/Jobs/ForwardAnalyticsData.php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Http;

class ForwardAnalyticsData implements ShouldQueue
{
    use Queueable;

    protected $url;
    protected $data;
    protected $headers;

    public function __construct(string $url, array $data, array $headers)
    {
        $this->url = $url;
        $this->data = $data;
        $this->headers = $headers;
    }

    public function handle()
    {
        Http::withHeaders($this->headers)
            ->post($this->url, $this->data);
    }
}
```

Use in controller for session replay:

```php
public function proxySessionReplay(Request $request, string $siteId)
{
    // Dispatch job for async processing
    ForwardAnalyticsData::dispatch(
        "{$this->rybbitHost}/api/session-replay/record/{$siteId}",
        $request->all(),
        [
            'X-Real-IP' => $request->ip(),
            'User-Agent' => $request->header('User-Agent'),
        ]
    );

    return response()->json(['status' => 'queued']);
}
```

### CORS Configuration [#cors-configuration]

If serving from a different domain:

```php
<?php
// config/cors.php

return [
    'paths' => ['analytics/*'],
    'allowed_methods' => ['GET', 'POST'],
    'allowed_origins' => ['https://yourdomain.com'],
    'allowed_headers' => ['Content-Type', 'X-Requested-With'],
];
```

## Troubleshooting [#troubleshooting]

### 404 Not Found [#404-not-found]

**Problem**: Routes return 404.

**Solution**:

1. Clear route cache: `php artisan route:clear`
2. List routes to verify: `php artisan route:list --path=analytics`
3. Check route order (more specific routes first)

### Session errors with POST requests [#session-errors-with-post-requests]

**Problem**: CSRF token errors on tracking endpoints.

**Solution**:
Exclude analytics routes from CSRF protection in `app/Http/Middleware/VerifyCsrfToken.php`:

```php
protected $except = [
    'analytics/*',
];
```

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show server's location.

**Solution**:
Ensure IP forwarding in controller:

```php
$clientIp = $request->header('X-Forwarded-For', $request->ip());
```

And add to HTTP request:

```php
'X-Real-IP' => $clientIp,
'X-Forwarded-For' => $clientIp,
```

### Cache not clearing [#cache-not-clearing]

**Problem**: Old script cached after Rybbit update.

**Solution**:
Clear specific cache key:

```bash
php artisan cache:forget rybbit_script_script.js
```

Or clear all cache:

```bash
php artisan cache:clear
```

## Performance Optimization [#performance-optimization]

### Cache Optimization [#cache-optimization]

```php
// Configure cache tags for easy clearing
Cache::tags(['rybbit', 'scripts'])->remember($cacheKey, 3600, function () {
    // ... fetch script
});

// Clear all Rybbit cache
Cache::tags(['rybbit'])->flush();
```

### HTTP Client Optimization [#http-client-optimization]

```php
// Use connection pooling
Http::pool(fn (Pool $pool) => [
    $pool->get("{$this->rybbitHost}/api/script.js"),
    $pool->get("{$this->rybbitHost}/api/replay.js"),
]);
```

## Related Resources [#related-resources]

* [Laravel Integration Guide](/docs/guides/laravel) - General Laravel integration
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Laravel HTTP Client](https://laravel.com/docs/http-client) - Official Laravel docs


# Next.js Proxy Setup (/de/docs/proxy-guide/next-js)





Next.js provides a powerful [rewrites](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) feature that makes it easy to proxy Rybbit tracking through your own domain. This guide works with both the App Router (Next.js 13+) and Pages Router.

<Callout type="info">
  Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**. Rewrites on this platform automatically forward the browser's headers and set `X-Forwarded-For` to the visitor IP — the toggle tells Rybbit to trust that forwarded IP directly.
</Callout>

## Overview [#overview]

Next.js rewrites allow you to map incoming request paths to different destination URLs transparently. This is perfect for proxying analytics since the browser sees requests to your domain while Next.js forwards them to Rybbit's servers behind the scenes.

**What you'll achieve:**

* Serve Rybbit scripts from your domain (e.g., `/analytics/script.js`)
* Proxy all tracking requests through your Next.js application
* Bypass ad blocker detection with first-party requests
* Support all Rybbit features (session replay, Web Vitals, custom events)

## Prerequisites [#prerequisites]

* Next.js 12 or later (rewrites are supported in all modern versions)
* Your Rybbit site ID (found in your dashboard)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL (e.g., `https://analytics.yourcompany.com`)

## Implementation [#implementation]

<Steps>
  ### Configure Environment Variables [#configure-environment-variables]

  Create or update your `.env` or `.env.local` file with your Rybbit instance URL:

  <Tabs items="['Cloud Hosted', 'Self-Hosted']">
    <Tab>
      ```bash
      # .env.local
      NEXT_PUBLIC_RYBBIT_HOST=https://app.rybbit.io
      ```
    </Tab>

    <Tab>
      ```bash
      # .env.local
      NEXT_PUBLIC_RYBBIT_HOST=https://analytics.yourcompany.com
      ```

      Replace `analytics.yourcompany.com` with your actual Rybbit instance domain.
    </Tab>
  </Tabs>

  <Callout type="info">
    The `NEXT_PUBLIC_` prefix makes this environment variable available in both server and client environments, though it's primarily used during build time for the rewrites configuration.
  </Callout>

  ### Set Up Rewrites in next.config.js [#set-up-rewrites-in-nextconfigjs]

  Add or update the `rewrites` function in your `next.config.js` (or `next.config.mjs` for ESM):

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'ESM (next.config.mjs)']">
    <Tab>
      This configuration proxies all Rybbit endpoints including session replay and Web Vitals:

      ```javascript
      // next.config.js
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            // Tracking scripts
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/replay.js',
              destination: `${rybbitHost}/api/replay.js`,
            },
            {
              source: '/analytics/metrics.js',
              destination: `${rybbitHost}/api/metrics.js`,
            },
            // Tracking endpoints
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
            {
              source: '/analytics/identify',
              destination: `${rybbitHost}/api/identify`,
            },
            {
              source: '/analytics/session-replay/record/:siteId',
              destination: `${rybbitHost}/api/session-replay/record/:siteId`,
            },
            {
              source: '/analytics/site/tracking-config/:siteId',
              destination: `${rybbitHost}/api/site/tracking-config/:siteId`,
            },
          ];
        },
      };

      module.exports = nextConfig;
      ```
    </Tab>

    <Tab>
      Minimal setup with just script loading and basic event tracking:

      ```javascript
      // next.config.js
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
          ];
        },
      };

      module.exports = nextConfig;
      ```

      <Callout type="warn">
        This minimal setup won't support session replay or Web Vitals. Use the full proxy configuration if you need these features.
      </Callout>
    </Tab>

    <Tab>
      If you're using ES modules:

      ```javascript
      // next.config.mjs
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
            {
              source: '/analytics/replay.js',
              destination: `${rybbitHost}/api/replay.js`,
            },
            {
              source: '/analytics/metrics.js',
              destination: `${rybbitHost}/api/metrics.js`,
            },
            {
              source: '/analytics/identify',
              destination: `${rybbitHost}/api/identify`,
            },
            {
              source: '/analytics/session-replay/record/:siteId',
              destination: `${rybbitHost}/api/session-replay/record/:siteId`,
            },
            {
              source: '/analytics/site/tracking-config/:siteId',
              destination: `${rybbitHost}/api/site/tracking-config/:siteId`,
            },
          ];
        },
      };

      export default nextConfig;
      ```
    </Tab>
  </Tabs>

  <Callout type="info">
    **Custom Path**: You can change `/analytics` to any path you prefer (e.g., `/tracking`, `/stats`, `/rybbit`). Just ensure you use the same path consistently in both your rewrites and script tag.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your script tag to load from the proxied path instead of directly from Rybbit:

  <Tabs items="['App Router (Next.js 13+)', 'Pages Router', 'JavaScript (No TypeScript)']">
    <Tab>
      Update your root layout file:

      ```tsx
      // app/layout.tsx
      import Script from 'next/script';

      export default function RootLayout({
        children,
      }: {
        children: React.ReactNode;
      }) {
        return (
          <html lang="en">
            <body>
              {children}
              <Script
                src="/analytics/script.js"
                data-site-id="YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </body>
          </html>
        );
      }
      ```

      Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.
    </Tab>

    <Tab>
      Update your `_app.tsx` or `_app.jsx` file:

      ```tsx
      // pages/_app.tsx
      import Script from 'next/script';
      import type { AppProps } from 'next/app';

      function MyApp({ Component, pageProps }: AppProps) {
        return (
          <>
            <Component {...pageProps} />
            <Script
              src="/analytics/script.js"
              data-site-id="YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </>
        );
      }

      export default MyApp;
      ```

      Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.
    </Tab>

    <Tab>
      ```jsx
      // app/layout.js or pages/_app.js
      import Script from 'next/script';

      export default function RootLayout({ children }) {
        return (
          <html lang="en">
            <body>
              {children}
              <Script
                src="/analytics/script.js"
                data-site-id="YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </body>
          </html>
        );
      }
      ```
    </Tab>
  </Tabs>

  ### Restart Your Development Server [#restart-your-development-server]

  After updating `next.config.js`, restart your Next.js development server for the changes to take effect:

  ```bash
  # Stop the server (Ctrl+C) and restart
  npm run dev
  # or
  yarn dev
  # or
  pnpm dev
  ```

  ### Verify the Setup [#verify-the-setup]

  Open your website in a browser with Developer Tools:

  1. **Open the Network tab** and filter by "analytics" or "script"
  2. **Verify the script loads**:
     * You should see a request to `/analytics/script.js` (not `app.rybbit.io`)
     * Status should be `200 OK`
     * The domain should be your own domain
  3. **Verify tracking works**:
     * Navigate to another page or trigger an event
     * You should see POST requests to `/analytics/track`
     * All requests should show your domain, not `app.rybbit.io`
  4. **Check the Rybbit dashboard**:
     * Wait 1-2 minutes for data processing
     * Verify your session appears in the real-time dashboard
</Steps>

## How It Works [#how-it-works]

The Rybbit tracking script has a built-in auto-discovery mechanism. When it loads from:

```html
<script src="/analytics/script.js" data-site-id="123"></script>
```

It automatically extracts the analytics host from its own `src` attribute:

```typescript
// Inside Rybbit's script
const scriptElement = document.currentScript;
const src = scriptElement.getAttribute('src');
const analyticsHost = src.split('/script.js')[0];
// Result: "" (empty string means same domain)
```

This means all tracking requests automatically go to `/analytics/track`, `/analytics/identify`, etc., which Next.js then rewrites to forward to Rybbit's servers.

## Performance Considerations [#performance-considerations]

### Bandwidth Usage [#bandwidth-usage]

All tracking requests now flow through your Next.js server, which will increase bandwidth usage:

<Callout type="warn">
  **Bandwidth Impact**: Each session typically uses 10-50 KB without session replay, or 50-500 KB with session replay enabled. For a site with 100,000 monthly sessions, expect 5-10 GB/month additional bandwidth without replay, or 30-80 GB/month with replay.
</Callout>

Most Vercel, Netlify, or other hosting plans can handle this, but check your plan's bandwidth limits if you have high traffic.

### Caching [#caching]

Next.js automatically caches responses when possible, but you can optimize further:

**Using Vercel Edge Network:**
If deployed on Vercel, your rewrites benefit from the global Edge Network, which caches static scripts close to users worldwide.

**Custom caching headers:**
The Rybbit server sets cache headers on its scripts, which Next.js respects:

* Scripts (`.js` files): Cached for 1 hour (`script.js`) to 1 day (`replay.js`, `metrics.js`)
* Configuration: Not cached by the server (you may cache it for \~5 minutes at your proxy if desired)
* Tracking POSTs: Not cached

### Server Load [#server-load]

Rewrites are handled at the edge on Vercel, so there's minimal impact on your serverless functions. For self-hosted Next.js, consider:

* Using a CDN (Cloudflare, CloudFront, etc.) in front of Next.js
* Scaling your server if you have very high traffic
* Monitoring server response times

## Troubleshooting [#troubleshooting]

### Script loads but events aren't tracked [#script-loads-but-events-arent-tracked]

**Problem**: You see the script load successfully, but no tracking data appears in the dashboard.

**Solution**:

1. Check that `/analytics/track` is included in your rewrites
2. Verify POST requests to `/analytics/track` return `200 OK` in Network tab
3. Check for CORS errors in the browser console
4. Ensure your Rybbit instance URL is correct in `.env.local`

### 404 errors on tracking endpoints [#404-errors-on-tracking-endpoints]

**Problem**: Script loads fine, but tracking requests return 404.

**Solution**:

1. Verify all tracking endpoints are in your `rewrites()` configuration
2. Restart your dev server after changing `next.config.js`
3. Clear your browser cache
4. Check that the endpoint paths exactly match (case-sensitive)

### Session replay not working [#session-replay-not-working]

**Problem**: Basic tracking works but session replay doesn't record.

**Solution**:
Add the session replay endpoints to your rewrites:

```javascript
{
  source: '/analytics/replay.js',
  destination: `${rybbitHost}/api/replay.js`,
},
{
  source: '/analytics/session-replay/record/:siteId',
  destination: `${rybbitHost}/api/session-replay/record/:siteId`,
},
```

### Environment variable not loading [#environment-variable-not-loading]

**Problem**: Rewrites don't work, console shows warning about missing `NEXT_PUBLIC_RYBBIT_HOST`.

**Solution**:

1. Ensure you created `.env.local` in your project root
2. Restart your dev server after creating `.env.local`
3. For production, ensure environment variables are set in your hosting platform (Vercel, Netlify, etc.)

## Deployment Considerations [#deployment-considerations]

### Vercel [#vercel]

When deploying to Vercel:

1. Add `NEXT_PUBLIC_RYBBIT_HOST` environment variable in your Vercel project settings
2. Rewrites automatically work at the edge with zero configuration
3. Bandwidth is generous on all Vercel plans

### Self-Hosted [#self-hosted]

When self-hosting Next.js:

1. Ensure environment variables are available to the Next.js process
2. Consider adding a CDN layer for better caching and reduced bandwidth
3. Monitor server load if you have high traffic

### Other Platforms (Netlify, AWS, etc.) [#other-platforms-netlify-aws-etc]

1. Set environment variables in your platform's settings
2. Verify rewrites are supported (most platforms support Next.js rewrites)
3. Check bandwidth limits for your plan

## Advanced Configuration [#advanced-configuration]

### Different paths for different environments [#different-paths-for-different-environments]

You can customize the proxy path based on the environment:

```javascript
// next.config.js
const nextConfig = {
  async rewrites() {
    const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;
    const analyticsPath = process.env.NODE_ENV === 'development'
      ? '/dev-analytics'
      : '/analytics';

    return [
      {
        source: `${analyticsPath}/script.js`,
        destination: `${rybbitHost}/api/script.js`,
      },
      // ... other rewrites
    ];
  },
};
```

### Conditional proxy (development only) [#conditional-proxy-development-only]

If you only want proxying in production:

```javascript
// next.config.js
const nextConfig = {
  async rewrites() {
    if (process.env.NODE_ENV === 'development') {
      return []; // No proxy in development
    }

    // ... production rewrites
  },
};
```

## Related Resources [#related-resources]

* [Next.js Integration Guide](/docs/guides/react/next-js) - General Next.js integration
* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Custom Events](/docs/track-events) - Track custom events
* [Next.js Rewrites Documentation](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) - Official Next.js docs


# Nginx Proxy Setup (/de/docs/proxy-guide/nginx)





Nginx is a powerful web server and reverse proxy that makes it easy to proxy Rybbit tracking through your own domain. This guide shows how to configure Nginx to forward tracking requests to Rybbit servers while caching static scripts for better performance.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Nginx's `proxy_pass` directive lets you forward requests from your domain to Rybbit's servers. Combined with caching, this provides excellent performance and reliability for proxying analytics.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your domain
* Cache static scripts for better performance
* Forward necessary headers for accurate tracking
* Support all Rybbit features (session replay, Web Vitals, custom events)

## Prerequisites [#prerequisites]

* Nginx installed (version 1.18 or later recommended)
* SSL/TLS certificate configured (Let's Encrypt recommended)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID (found in your dashboard)

## Implementation [#implementation]

<Steps>
  ### Configure Nginx Proxy [#configure-nginx-proxy]

  Add a new location block (or update existing configuration) in your Nginx site configuration:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'With Cache Zone']">
    <Tab>
      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          listen 443 ssl http2;
          server_name yourdomain.com;

          # Your SSL configuration
          ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
          ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

          # Your main site configuration
          location / {
              # Your regular site config...
          }

          # Rybbit Analytics Proxy
          # Main tracking script (cached)
          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              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;

              # Cache for 1 hour
              proxy_cache_valid 200 1h;
              proxy_cache_bypass $http_cache_control;
              add_header X-Cache-Status $upstream_cache_status;
          }

          # Session replay script (cached)
          location = /analytics/replay.js {
              proxy_pass https://app.rybbit.io/api/replay.js;
              proxy_set_header Host app.rybbit.io;
              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;

              proxy_cache_valid 200 1h;
          }

          # Web Vitals metrics script (cached)
          location = /analytics/metrics.js {
              proxy_pass https://app.rybbit.io/api/metrics.js;
              proxy_set_header Host app.rybbit.io;
              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;

              proxy_cache_valid 200 1h;
          }

          # Event tracking endpoint (not cached)
          location = /analytics/track {
              proxy_pass https://app.rybbit.io/api/track;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;
          }

          # User identification endpoint (not cached)
          location = /analytics/identify {
              proxy_pass https://app.rybbit.io/api/identify;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;
          }

          # Session replay recording endpoint (not cached)
          location ~ ^/analytics/session-replay/record/(.*)$ {
              proxy_pass https://app.rybbit.io/api/session-replay/record/$1;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;

              # Allow larger uploads for session replay
              client_max_body_size 10M;
          }

          # Site configuration endpoint (cached briefly)
          location ~ ^/analytics/site/tracking-config/(.*)$ {
              proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
              proxy_set_header Host app.rybbit.io;
              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;

              # Cache for 5 minutes
              proxy_cache_valid 200 5m;
          }
      }
      ```

      <Callout type="info">
        Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
      </Callout>
    </Tab>

    <Tab>
      Minimal configuration for basic tracking:

      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          listen 443 ssl http2;
          server_name yourdomain.com;

          # SSL configuration
          ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
          ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

          # Main tracking script
          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;

              proxy_cache_valid 200 1h;
          }

          # Event tracking
          location = /analytics/track {
              proxy_pass https://app.rybbit.io/api/track;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;
          }
      }
      ```
    </Tab>

    <Tab>
      For better performance with caching, define a cache zone:

      ```nginx
      # /etc/nginx/nginx.conf (http block)
      http {
          # Define cache zone for Rybbit
          proxy_cache_path /var/cache/nginx/rybbit
              levels=1:2
              keys_zone=rybbit_cache:10m
              max_size=100m
              inactive=60m
              use_temp_path=off;

          # ... rest of http config
      }
      ```

      Then in your site config:

      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          # ... server config

          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;

              # Use the cache zone
              proxy_cache rybbit_cache;
              proxy_cache_valid 200 1h;
              proxy_cache_key "$scheme$request_method$host$request_uri";
              add_header X-Cache-Status $upstream_cache_status;
          }

          # ... other locations
      }
      ```
    </Tab>
  </Tabs>

  <Callout type="warn">
    **Important**: The `proxy_set_header X-Real-IP` and `X-Forwarded-For` headers are critical for accurate geolocation and user identification. Without these, all traffic will appear to come from your Nginx server's IP.
  </Callout>

  ### Create Cache Directory (Optional) [#create-cache-directory-optional]

  If using a cache zone, create the cache directory:

  ```bash
  sudo mkdir -p /var/cache/nginx/rybbit
  sudo chown www-data:www-data /var/cache/nginx/rybbit
  ```

  ### Test Nginx Configuration [#test-nginx-configuration]

  Before reloading Nginx, test the configuration for syntax errors:

  ```bash
  sudo nginx -t
  ```

  You should see:

  ```
  nginx: configuration file /etc/nginx/nginx.conf test is successful
  ```

  ### Reload Nginx [#reload-nginx]

  Apply the changes by reloading Nginx:

  ```bash
  sudo systemctl reload nginx
  ```

  Or if you prefer:

  ```bash
  sudo nginx -s reload
  ```

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to load the script from your proxied domain:

  ```html
  <!DOCTYPE html>
  <html>
  <head>
      <!-- ... other head elements -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      <!-- Your content -->
  </body>
  </html>
  ```

  Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.

  ### Verify the Setup [#verify-the-setup]

  Test your configuration:

  1. **Check Nginx is running**:
     ```bash
     sudo systemctl status nginx
     ```

  2. **Test script loading**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see:

     ```
     HTTP/2 200
     content-type: application/javascript
     x-cache-status: MISS  # First request
     ```

  3. **Test again to verify caching**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see:

     ```
     HTTP/2 200
     x-cache-status: HIT  # Cached!
     ```

  4. **Open your website** in a browser with Developer Tools and verify:
     * Script loads from `/analytics/script.js` (your domain)
     * Tracking requests go to `/analytics/track` (your domain)
     * Data appears in your Rybbit dashboard after 1-2 minutes
</Steps>

## How It Works [#how-it-works]

Nginx's `proxy_pass` directive transparently forwards requests to Rybbit's servers:

1. Browser requests `https://yourdomain.com/analytics/script.js`
2. Nginx matches the location block and forwards to `https://app.rybbit.io/api/script.js`
3. Nginx sets necessary headers (`X-Real-IP`, `X-Forwarded-For`) for accurate tracking
4. Response is cached (if configured) and sent back to browser
5. All subsequent tracking requests follow the same pattern

The Rybbit script auto-detects it's being served from your domain and sends all tracking data to your domain's `/analytics/*` endpoints.

## Performance Optimization [#performance-optimization]

### Caching Strategy [#caching-strategy]

Configure different cache durations based on content type:

```nginx
# Scripts - cache for 1 hour
location ~ ^/analytics/(script|replay|metrics)\.js$ {
    proxy_pass https://app.rybbit.io/api/$1.js;
    # ... proxy headers
    proxy_cache_valid 200 1h;
    proxy_cache_valid 404 1m;  # Cache 404s briefly
}

# Config - cache for 5 minutes (changes when you update dashboard settings)
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
    # ... proxy headers
    proxy_cache_valid 200 5m;
}

# Tracking - never cache (each request is unique)
location ~ ^/analytics/(track|identify)$ {
    proxy_pass https://app.rybbit.io/api/$1;
    # ... proxy headers
    # No caching directives
}
```

### Gzip Compression [#gzip-compression]

Enable compression for JavaScript files:

```nginx
# In http or server block
gzip on;
gzip_vary on;
gzip_types application/javascript text/javascript;
gzip_min_length 1000;
```

### Connection Pooling [#connection-pooling]

Keep connections to Rybbit backend alive for better performance:

```nginx
upstream rybbit_backend {
    server app.rybbit.io:443;
    keepalive 32;
}

location /analytics/ {
    proxy_pass https://rybbit_backend/api/;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    # ... other proxy headers
}
```

### Proxy Buffering [#proxy-buffering]

For better performance with larger session replay uploads:

```nginx
location ~ ^/analytics/session-replay/record/ {
    proxy_pass https://app.rybbit.io/api/session-replay/record/;
    # ... proxy headers

    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;
    proxy_busy_buffers_size 8k;
    client_max_body_size 10M;
}
```

## Security Considerations [#security-considerations]

### Rate Limiting [#rate-limiting]

Protect your proxy from abuse with rate limiting:

```nginx
# In http block
http {
    limit_req_zone $binary_remote_addr zone=analytics_limit:10m rate=10r/s;

    # ... rest of config
}

# In server block
location = /analytics/track {
    limit_req zone=analytics_limit burst=20 nodelay;
    proxy_pass https://app.rybbit.io/api/track;
    # ... proxy headers
}
```

This limits to 10 requests per second per IP, with bursts up to 20.

### Request Size Limits [#request-size-limits]

Set appropriate limits for different endpoints:

```nginx
# Default for most endpoints
client_max_body_size 1M;

# Larger limit for session replay
location ~ ^/analytics/session-replay/record/ {
    client_max_body_size 10M;
    # ... proxy config
}
```

### Security Headers [#security-headers]

Add security headers to your responses:

```nginx
add_header X-Content-Type-Options nosniff;
add_header X-Frame-Options DENY;
add_header Referrer-Policy strict-origin-when-cross-origin;
```

## Troubleshooting [#troubleshooting]

### 502 Bad Gateway [#502-bad-gateway]

**Problem**: Nginx returns 502 error when accessing analytics endpoints.

**Solution**:

1. Check Rybbit backend is accessible:
   ```bash
   curl -I https://app.rybbit.io/api/script.js
   ```
2. Verify `proxy_ssl_server_name on` is set
3. Check Nginx error logs:
   ```bash
   sudo tail -f /var/log/nginx/error.log
   ```

### Cache not working [#cache-not-working]

**Problem**: `X-Cache-Status` always shows `MISS`.

**Solution**:

1. Verify cache directory exists and is writable
2. Check `proxy_cache_path` is defined in http block
3. Ensure `proxy_cache` directive uses correct zone name
4. Check cache key is consistent:
   ```nginx
   proxy_cache_key "$scheme$request_method$host$request_uri";
   ```

### Incorrect geolocation in Rybbit [#incorrect-geolocation-in-rybbit]

**Problem**: All visitors show same location (your server's location).

**Solution**:
Ensure you're forwarding client IP headers:

```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
```

### SSL errors in Nginx logs [#ssl-errors-in-nginx-logs]

**Problem**: Logs show SSL verification errors when connecting to Rybbit.

**Solution**:
Add `proxy_ssl_server_name on` to enable SNI:

```nginx
location /analytics/ {
    proxy_pass https://app.rybbit.io/api/;
    proxy_ssl_server_name on;  # Enable SNI
    # ... other config
}
```

## Advanced Configuration [#advanced-configuration]

### Subdomain Proxy [#subdomain-proxy]

Use a dedicated subdomain for analytics:

```nginx
# /etc/nginx/sites-available/analytics.yourdomain.com
server {
    listen 443 ssl http2;
    server_name analytics.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/analytics.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.yourdomain.com/privkey.pem;

    # Proxy all requests to Rybbit
    location / {
        proxy_pass https://app.rybbit.io/api/;
        proxy_set_header Host app.rybbit.io;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_ssl_server_name on;
    }
}
```

Then use:

```html
<script src="https://analytics.yourdomain.com/script.js" data-site-id="123"></script>
```

### Multiple Rybbit Instances [#multiple-rybbit-instances]

If you need to proxy multiple Rybbit instances:

```nginx
location /analytics-prod/ {
    proxy_pass https://prod.rybbit.io/api/;
    # ... proxy config
}

location /analytics-staging/ {
    proxy_pass https://staging.rybbit.io/api/;
    # ... proxy config
}
```

## Related Resources [#related-resources]

* [Nginx Custom Configuration Guide](/docs/self-hosting-guides/custom-nginx) - Self-hosting Rybbit with Nginx
* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Framework-agnostic concepts
* [Nginx Proxy Module](http://nginx.org/en/docs/http/ngx_http_proxy_module.html) - Official Nginx documentation


# Troubleshooting Proxy Setup (/de/docs/proxy-guide/troubleshooting)





This guide covers common issues you might encounter when setting up a Rybbit proxy and how to resolve them.

## Script Loading Issues [#script-loading-issues]

### Script Fails to Load (404 Error) [#script-fails-to-load-404-error]

**Symptoms:**

* Network tab shows 404 for `/analytics/script.js`
* Console errors about failed script loading
* No tracking data in dashboard

**Solutions:**

<Steps>
  ### Verify Proxy Configuration [#verify-proxy-configuration]

  Check your proxy rules are correctly configured:

  * **Next.js**: Ensure rewrites are in `next.config.js` and server is restarted
  * **Nginx**: Verify location blocks are active and Nginx is reloaded
  * **Caddy**: Check Caddyfile syntax with `caddy validate`
  * **Workers**: Verify route is configured in Cloudflare dashboard

  ### Check Path Mapping [#check-path-mapping]

  Ensure paths are correctly mapped:

  ```
  Your domain          →  Rybbit backend
  -----------------        ---------------
  /analytics/script.js →  /api/script.js
  ```

  Common mistakes:

  * Wrong source path (`/tracking` instead of `/analytics`)
  * Incorrect destination (missing `/api` prefix)
  * Typos in configuration

  ### Test Direct Backend Access [#test-direct-backend-access]

  Verify Rybbit backend is accessible:

  ```bash
  curl -I https://app.rybbit.io/api/script.js
  ```

  Should return `HTTP/2 200` with `content-type: application/javascript`.
</Steps>

***

### Script Loads but Returns HTML [#script-loads-but-returns-html]

**Symptoms:**

* Script loads with 200 status
* Content-Type is `text/html` instead of `application/javascript`
* Console errors about unexpected token `<`

**Cause:** Proxy is serving your application's 404 page instead of proxying.

**Solutions:**

1. **Ensure proxy runs before app routing**:
   * Next.js: Rewrites run automatically before pages
   * Express: Define proxy routes BEFORE catch-all routes
   * Laravel: Place proxy routes at the top of `web.php`

2. **Check route specificity**:

```javascript
// ❌ Wrong order - catch-all comes first
app.get('*', (req, res) => res.sendFile('index.html'));
app.use('/analytics', proxyMiddleware);

// ✅ Correct order - proxy comes first
app.use('/analytics', proxyMiddleware);
app.get('*', (req, res) => res.sendFile('index.html'));
```

***

## Tracking Issues [#tracking-issues]

### Script Loads but No Events Tracked [#script-loads-but-no-events-tracked]

**Symptoms:**

* Script loads successfully
* No errors in console
* No tracking data appears in Rybbit dashboard
* POST requests to `/analytics/track` fail or return errors

**Solutions:**

<Steps>
  ### Verify All Endpoints Are Proxied [#verify-all-endpoints-are-proxied]

  Ensure tracking endpoints are configured:

  * `/analytics/track` (required)
  * `/analytics/identify` (for user identification)
  * `/analytics/session-replay/record/:siteId` (for session replay)
  * `/analytics/site/tracking-config/:siteId` (for configuration)

  **Check Network tab**: Look for failed POST requests to `/analytics/track`.

  ### Check CORS Headers [#check-cors-headers]

  Tracking endpoints need proper CORS headers. Rybbit sets these automatically, but ensure your proxy preserves them:

  ```nginx
  # Nginx - preserve CORS headers
  proxy_pass_header Access-Control-Allow-Origin;
  proxy_pass_header Access-Control-Allow-Methods;
  ```

  ```javascript
  // Express - don't override CORS
  // ❌ Wrong - blocks CORS
  app.use('/analytics', cors({ origin: 'https://yourdomain.com' }));

  // ✅ Correct - allow all origins (or use Rybbit's headers)
  app.use('/analytics', cors({ origin: true }));
  ```

  ### Verify Content-Type for POST Requests [#verify-content-type-for-post-requests]

  Tracking POSTs send JSON data. Ensure Content-Type is preserved:

  ```nginx
  # Nginx
  proxy_set_header Content-Type $content_type;
  ```

  ```javascript
  // Express
  onProxyReq: (proxyReq, req) => {
    if (req.headers['content-type']) {
      proxyReq.setHeader('Content-Type', req.headers['content-type']);
    }
  }
  ```

  ### Check Request Method Preservation [#check-request-method-preservation]

  Ensure POST requests remain POST:

  ```nginx
  # Nginx - correct
  proxy_method $request_method;

  # Or let it default (preserves method)
  proxy_pass https://app.rybbit.io;
  ```
</Steps>

***

### Events Tracked but Dashboard Shows Wrong Data [#events-tracked-but-dashboard-shows-wrong-data]

**Symptoms:**

* Events appear in dashboard
* But geolocation is wrong (all same location)
* Or user agents are incorrect

**Cause:** Client IP or headers not forwarded properly.

**Solutions:**

<Callout type="warn">
  **Critical**: The `X-Forwarded-For` header must contain the original client IP for accurate geolocation and user identification, and the **First-Party Proxy** toggle must be enabled in your site settings. Don't rely on `X-Real-IP` — on Rybbit Cloud it never reaches the backend (our edge network consumes it), and AWS CloudFront cannot send it at all.
</Callout>

**Nginx:**

```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header User-Agent $http_user_agent;
```

**Caddy:**

```txt
reverse_proxy https://app.rybbit.io {
    header_up X-Real-IP {remote_host}
    header_up X-Forwarded-For {remote_host}
}
```

**Express:**

```javascript
onProxyReq: (proxyReq, req) => {
  const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  proxyReq.setHeader('X-Real-IP', clientIp);
  proxyReq.setHeader('X-Forwarded-For', clientIp);
  proxyReq.setHeader('User-Agent', req.headers['user-agent']);
}
```

**Cloudflare Workers:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';
proxyHeaders.set('X-Forwarded-For', clientIp);
```

***

### Proxied Requests Are Detected as Bots [#proxied-requests-are-detected-as-bots]

**Symptoms:**

* `/analytics/track` returns `200 OK`
* Events do not appear in the normal analytics dashboard (only under bot traffic)
* Tracking works fine when the script talks to Rybbit directly, without the proxy

There are two independent causes, and server-side proxies often hit **both**. Work through them in order.

#### Cause 1: Your proxy strips the browser's headers [#cause-1-your-proxy-strips-the-browsers-headers]

Rybbit's bot detection scores requests on headers that every real browser sends: `Accept`, `Accept-Language`, `Accept-Encoding` (with `gzip`), and the `Sec-Fetch-*` headers that all Chromium browsers attach. A proxy that forwards only `User-Agent` and the visitor IP produces requests indistinguishable from a script — they are accepted with `200 OK` but classified as bots.

**Fix:** forward **all** incoming request headers, minus `Host` and hop-by-hop headers (`Connection`, `Content-Length`). Hand-picking headers is the most common mistake in PHP/WordPress-style proxies.

```php
// PHP example — forward everything except Host/hop-by-hop
$headers = [];
foreach (getallheaders() as $name => $value) {
    if (!in_array(strtolower($name), ['host', 'connection', 'content-length'])) {
        $headers[] = "$name: $value";
    }
}
$headers[] = 'X-Forwarded-For: ' . $_SERVER['REMOTE_ADDR'];
```

#### Cause 2: Rybbit sees your proxy's IP instead of the visitor's [#cause-2-rybbit-sees-your-proxys-ip-instead-of-the-visitors]

First-party proxies typically run on hosting/datacenter infrastructure, so if the visitor IP is not forwarded (or not trusted), traffic carries a datacenter ASN and reinforces bot classification — and geolocation points at your proxy's region.

**Fix:**

1. Set `X-Forwarded-For` to the original visitor IP before forwarding to Rybbit.
2. Enable the **First-Party Proxy** toggle in **Site Settings → Privacy & Security** so Rybbit trusts the forwarded IP unconditionally.

<Callout type="warn">
  Use `X-Forwarded-For`, not `X-Real-IP`. On Rybbit Cloud, `X-Real-IP` never reaches the backend (our edge network consumes it), and AWS CloudFront cannot send it at all.
</Callout>

**Cloudflare Workers:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

const proxyHeaders = new Headers(request.headers); // preserves all browser headers
proxyHeaders.set('X-Forwarded-For', clientIp);
```

**AWS CloudFront:**

* Set `X-Forwarded-For` to the viewer IP from a CloudFront Function/Lambda\@Edge
* Configure the origin request policy to forward all viewer headers

```javascript
// CloudFront Function (viewer-request)
function handler(event) {
  event.request.headers["x-forwarded-for"] = { value: event.viewer.ip };
  return event.request;
}
```

***

## Session Replay Issues [#session-replay-issues]

### Session Replay Not Working [#session-replay-not-working]

**Symptoms:**

* Basic tracking works fine
* Session replays don't appear in dashboard
* Console shows errors loading `/analytics/replay.js`

**Solutions:**

1. **Add replay script endpoint**:

```javascript
// Next.js
{
  source: '/analytics/replay.js',
  destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/replay.js`,
}
```

2. **Add replay recording endpoint**:

```javascript
{
  source: '/analytics/session-replay/record/:siteId',
  destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/session-replay/record/:siteId`,
}
```

3. **Increase request size limits**:

Session replay can send large payloads (up to 10MB). Ensure your proxy allows this:

```nginx
# Nginx
location ~ ^/analytics/session-replay/record/ {
    client_max_body_size 10M;
    proxy_pass https://app.rybbit.io;
}
```

```javascript
// Express
app.use('/analytics/session-replay', express.json({ limit: '10mb' }));
```

```javascript
// Next.js - add to next.config.js
module.exports = {
  api: {
    bodyParser: {
      sizeLimit: '10mb',
    },
  },
};
```

***

## Configuration and Caching Issues [#configuration-and-caching-issues]

### Stale Configuration (Settings Changes Not Applied) [#stale-configuration-settings-changes-not-applied]

**Symptoms:**

* Changed settings in Rybbit dashboard
* But tracking script still uses old settings
* Takes a long time for changes to appear

**Cause:** Configuration endpoint is cached too aggressively.

**Solutions:**

1. **Check cache duration** for config endpoint:

```nginx
# Nginx - cache for 5 minutes max
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_cache_valid 200 5m;  # Not longer!
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
}
```

2. **Clear cache manually**:

```bash
# Nginx
sudo nginx -s reload

# Or clear cache directory
sudo rm -rf /var/cache/nginx/rybbit/*
```

```javascript
// Node.js/Express with node-cache
cache.del(`rybbit_config_${siteId}`);

// Or flush all
cache.flushAll();
```

3. **Don't cache config endpoint at all** (if issues persist):

```nginx
# Nginx - no caching
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_cache off;
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
}
```

***

### Script Updates Not Appearing [#script-updates-not-appearing]

**Symptoms:**

* Rybbit released an update
* Your site still loads old script version
* Missing new features or bug fixes

**Cause:** Script cached too long.

**Solutions:**

1. **Recommended cache duration**: 1 hour maximum

```nginx
# Nginx
proxy_cache_valid 200 1h;  # Not longer!
```

2. **Clear script cache**:

```bash
# Nginx - purge cache
sudo rm -rf /var/cache/nginx/rybbit/
sudo nginx -s reload
```

```bash
# Vercel - clear via dashboard
# Deployments → Your deployment → Clear cache
```

```javascript
// Cloudflare Workers - purge via dashboard
// Caching → Configuration → Purge Everything
```

3. **Add cache busting** (advanced):

```javascript
// Next.js - revalidate on each deployment
{
  source: '/analytics/script.js',
  destination: `${rybbitHost}/api/script.js`,
  headers: [
    {
      key: 'Cache-Control',
      value: 'public, max-age=3600, must-revalidate',
    },
  ],
}
```

***

## Performance Issues [#performance-issues]

### High Bandwidth Usage [#high-bandwidth-usage]

**Symptoms:**

* Bandwidth costs increasing significantly
* Server struggling with traffic
* Slow response times

**Solutions:**

<Steps>
  ### Implement Caching [#implement-caching]

  Cache static scripts to reduce backend requests:

  ```nginx
  # Nginx with caching
  proxy_cache_path /var/cache/nginx/rybbit levels=1:2 keys_zone=rybbit:10m;

  location = /analytics/script.js {
      proxy_cache rybbit;
      proxy_cache_valid 200 1h;
      proxy_cache_key "$scheme$request_method$host$request_uri";
      add_header X-Cache-Status $upstream_cache_status;
      proxy_pass https://app.rybbit.io/api/script.js;
  }
  ```

  ### Use CDN [#use-cdn]

  Put a CDN in front of your proxy:

  * Cloudflare (recommended)
  * AWS CloudFront
  * Fastly

  ### Monitor and Limit [#monitor-and-limit]

  Add monitoring and rate limiting:

  ```javascript
  // Express with rate limiting
  const rateLimit = require('express-rate-limit');

  app.use('/analytics/track', rateLimit({
    windowMs: 60 * 1000,
    max: 100, // 100 requests per minute per IP
  }));
  ```
</Steps>

***

### Slow Response Times [#slow-response-times]

**Symptoms:**

* Tracking requests take multiple seconds
* Script loading is slow
* Poor user experience

**Solutions:**

1. **Enable compression**:

```nginx
# Nginx
gzip on;
gzip_types application/javascript;
```

2. **Use connection keepalive**:

```nginx
# Nginx
proxy_http_version 1.1;
proxy_set_header Connection "";

upstream rybbit {
    server app.rybbit.io:443;
    keepalive 32;
}
```

3. **Check backend connectivity**:

```bash
# Test latency to Rybbit
curl -w "@curl-format.txt" -o /dev/null -s https://app.rybbit.io/api/script.js

# Create curl-format.txt:
# time_namelookup:  %{time_namelookup}s
# time_connect:     %{time_connect}s
# time_starttransfer: %{time_starttransfer}s
# time_total:       %{time_total}s
```

If backend is slow, consider:

* Self-hosting Rybbit closer to your users
* Using a CDN proxy
* Caching more aggressively

***

## Platform-Specific Issues [#platform-specific-issues]

### Next.js: Rewrites Not Working [#nextjs-rewrites-not-working]

**Problem:** Added rewrites to `next.config.js` but they don't work.

**Solutions:**

1. **Restart dev server**:

```bash
# Stop server (Ctrl+C)
npm run dev
```

2. **Check async rewrites** function:

```javascript
// ❌ Wrong - not async
rewrites() {
    return [...];
}

// ✅ Correct - async
async rewrites() {
    return [...];
}
```

3. **Verify environment variable** is loaded:

```javascript
async rewrites() {
    console.log('RYBBIT_HOST:', process.env.NEXT_PUBLIC_RYBBIT_HOST);
    // Should log the URL
    return [...];
}
```

***

### Nginx: 502 Bad Gateway [#nginx-502-bad-gateway]

**Problem:** Nginx returns 502 error for analytics endpoints.

**Solutions:**

1. **Enable SNI** for SSL:

```nginx
proxy_ssl_server_name on;
```

2. **Check DNS resolution**:

```bash
nslookup app.rybbit.io
```

3. **Check logs**:

```bash
sudo tail -f /var/log/nginx/error.log
```

4. **Test backend directly**:

```bash
curl -v https://app.rybbit.io/api/script.js
```

***

### Vercel: 404 After Deployment [#vercel-404-after-deployment]

**Problem:** Works locally but 404 in production.

**Solutions:**

1. **Ensure `vercel.json` is committed**:

```bash
git add vercel.json
git commit -m "Add Rybbit proxy config"
git push
```

2. **Check build logs** in Vercel dashboard for errors

3. **Verify environment variables** are set in Vercel project settings

***

## Debugging Checklist [#debugging-checklist]

When troubleshooting, work through this checklist:

* [ ] Script loads successfully (200 status, correct Content-Type)
* [ ] Tracking endpoint is proxied (`/analytics/track`)
* [ ] POST requests preserve method and body
* [ ] Client IP is forwarded in `X-Forwarded-For` (not just `X-Real-IP` — that header doesn't survive Rybbit Cloud's edge)
* [ ] **First-Party Proxy** toggle is enabled in Site Settings → Privacy & Security
* [ ] Full browser header set is forwarded (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — not just `User-Agent`
* [ ] User-Agent header is preserved
* [ ] CORS headers are preserved (check response headers)
* [ ] Request size limits allow tracking data (1MB minimum)
* [ ] Session replay endpoints are proxied (if using replay)
* [ ] Cache duration is appropriate (1 hour for scripts, 5 min for config)
* [ ] No CSRF protection blocking POST requests
* [ ] Environment variables are set correctly
* [ ] Configuration changes have been deployed

## Getting Help [#getting-help]

If you've tried everything and still have issues:

1. **Check browser console** for JavaScript errors
2. **Check Network tab** for failed requests (note status codes)
3. **Check server logs** for proxy errors
4. **Test with curl** to isolate browser vs server issues
5. **Verify directly** against `https://app.rybbit.io/api/script.js`

**Gather this information before asking for help:**

* Framework/platform you're using
* Proxy configuration code
* Network tab screenshot showing the issue
* Any error messages from logs or console
* Whether it worked before (what changed?)

## Related Resources [#related-resources]

* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [Tracking Script Documentation](/docs/script) - Script configuration
* Framework-specific guides for detailed setup


# Vercel Proxy Setup (/de/docs/proxy-guide/vercel)





Vercel makes it easy to proxy Rybbit tracking through their Edge Network. If you're using Next.js, follow the [Next.js proxy guide](/docs/proxy-guide/next-js) instead, which is optimized for Next.js applications.

This guide is for static sites or other frameworks deployed on Vercel.

<Callout type="info">
  Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**. Rewrites on this platform automatically forward the browser's headers and set `X-Forwarded-For` to the visitor IP — the toggle tells Rybbit to trust that forwarded IP directly.
</Callout>

## Overview [#overview]

Vercel supports rewrites in `vercel.json`, allowing you to proxy requests through their global Edge Network. This provides excellent performance with automatic caching at edge locations worldwide.

**What you'll achieve:**

* Proxy Rybbit through Vercel's Edge Network
* Automatic global caching and CDN distribution
* Simple JSON configuration
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Site deployed on Vercel
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Create or Update vercel.json [#create-or-update-verceljson]

  Add rewrites to your `vercel.json` file in the project root:

  ```json
  {
    "rewrites": [
      {
        "source": "/analytics/script.js",
        "destination": "https://app.rybbit.io/api/script.js"
      },
      {
        "source": "/analytics/replay.js",
        "destination": "https://app.rybbit.io/api/replay.js"
      },
      {
        "source": "/analytics/metrics.js",
        "destination": "https://app.rybbit.io/api/metrics.js"
      },
      {
        "source": "/analytics/track",
        "destination": "https://app.rybbit.io/api/track"
      },
      {
        "source": "/analytics/identify",
        "destination": "https://app.rybbit.io/api/identify"
      },
      {
        "source": "/analytics/session-replay/record/:siteId",
        "destination": "https://app.rybbit.io/api/session-replay/record/:siteId"
      },
      {
        "source": "/analytics/site/tracking-config/:siteId",
        "destination": "https://app.rybbit.io/api/site/tracking-config/:siteId"
      }
    ]
  }
  ```

  <Callout type="info">
    Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to use the proxied path:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Deploy to Vercel [#deploy-to-vercel]

  Commit your changes and deploy:

  ```bash
  git add vercel.json
  git commit -m "Add Rybbit proxy configuration"
  git push
  ```

  Vercel will automatically detect the changes and deploy with the new rewrites.

  ### Verify the Setup [#verify-the-setup]

  1. **Visit your deployed site** with Developer Tools open
  2. **Check Network tab**:
     * Script should load from `/analytics/script.js`
     * Tracking requests should go to `/analytics/track`
     * All requests should show your Vercel domain
  3. **Verify in Rybbit dashboard**: Data should appear after 1-2 minutes
</Steps>

## How It Works [#how-it-works]

Vercel's Edge Network handles rewrites at the edge, close to your users:

1. Request hits Vercel's edge location nearest to the user
2. Edge server rewrites and proxies to Rybbit
3. Response is cached at the edge (for cacheable requests)
4. Subsequent requests serve from edge cache

This provides excellent performance with minimal configuration.

## Performance Benefits [#performance-benefits]

### Edge Network Caching [#edge-network-caching]

Vercel automatically caches responses at edge locations:

* **Scripts**: Cached globally, served from nearest edge
* **Configuration**: Cached with appropriate TTL
* **Tracking requests**: Not cached (unique per request)

### Global Distribution [#global-distribution]

Your analytics proxy benefits from Vercel's global CDN:

* 70+ edge locations worldwide
* Sub-100ms latency for most users
* Automatic failover and redundancy

## Bandwidth Considerations [#bandwidth-considerations]

<Callout type="warn">
  Vercel rewrites count toward your bandwidth quota. For a site with 100,000 monthly sessions:

  * Without session replay: \~5-10 GB/month
  * With session replay: \~30-80 GB/month

  Check your Vercel plan limits. Pro plan includes 1 TB bandwidth/month.
</Callout>

## Troubleshooting [#troubleshooting]

### Rewrites not working [#rewrites-not-working]

**Problem**: Requests still go to `app.rybbit.io` directly.

**Solution**:

1. Ensure `vercel.json` is in your project root
2. Redeploy after adding `vercel.json`
3. Clear browser cache and test in incognito mode

### 404 on tracking endpoints [#404-on-tracking-endpoints]

**Problem**: Script loads but tracking returns 404.

**Solution**:
Verify all endpoints are in `vercel.json` rewrites, including:

* `/analytics/track`
* `/analytics/identify`
* `/analytics/session-replay/record/:siteId`

### Session replay not working [#session-replay-not-working]

**Problem**: Basic tracking works but replay doesn't record.

**Solution**:
Add replay endpoints to rewrites:

```json
{
  "source": "/analytics/replay.js",
  "destination": "https://app.rybbit.io/api/replay.js"
},
{
  "source": "/analytics/session-replay/record/:siteId",
  "destination": "https://app.rybbit.io/api/session-replay/record/:siteId"
}
```

## Environment-Specific Configuration [#environment-specific-configuration]

### Using Environment Variables [#using-environment-variables]

While Vercel's `vercel.json` doesn't support environment variables directly, you can use different config files:

```json
// vercel.json (production)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}
```

```json
// vercel.staging.json (staging)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://staging.rybbit.io/api/script.js"
    }
  ]
}
```

Then specify config in build settings or use Vercel CLI:

```bash
vercel --prod --local-config vercel.json
```

## Advanced Configuration [#advanced-configuration]

### Headers [#headers]

Add custom headers to responses:

```json
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ],
  "headers": [
    {
      "source": "/analytics/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=3600"
        }
      ]
    }
  ]
}
```

### Redirects vs Rewrites [#redirects-vs-rewrites]

Don't use redirects for proxying (they're visible to the user):

```json
// ❌ Wrong - uses redirects (user sees app.rybbit.io)
{
  "redirects": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}

// ✅ Correct - uses rewrites (transparent proxy)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}
```

## Related Resources [#related-resources]

* [Next.js Proxy Guide](/docs/proxy-guide/next-js) - If using Next.js
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Vercel Rewrites Documentation](https://vercel.com/docs/projects/project-configuration#rewrites) - Official Vercel docs


# JavaScript (Node.js) (/de/docs/sdks/node)





## Installation [#installation]

```bash filename="npm"
npm install @rybbit/node
```

```bash filename="yarn"
yarn add @rybbit/node
```

## Initialization [#initialization]

### Syntax [#syntax]

```typescript
import { Rybbit } from "@rybbit/node";

const rybbit = new Rybbit(config: RybbitConfig);
```

### Example [#example]

```javascript
import { Rybbit } from "@rybbit/node";

const rybbit = new Rybbit({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  apiKey: "your-secret-api-key",
});
```

<Callout type="warning">
  The `Rybbit` constructor will throw an error if required configuration options (`analyticsHost`, `siteId`, `apiKey`) are missing or invalid.
</Callout>

### Configuration Options [#configuration-options]

| Option          | Type               | Default | Description                                                                                      |
| :-------------- | :----------------- | :------ | :----------------------------------------------------------------------------------------------- |
| `analyticsHost` | `string`           | -       | **Required.** URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |
| `siteId`        | `string \| number` | -       | **Required.** The Site ID for your website obtained from your Rybbit instance.                   |
| `apiKey`        | `string`           | -       | **Required.** Your secret API key for the site                                                   |
| `debug`         | `boolean`          | `false` | Enable detailed logging to the console.                                                          |

## Tracking Pageviews [#tracking-pageviews]

While pageviews are traditionally a browser concept, the Node.js SDK provides a `pageview` method to track events that are analogous to a user viewing a page or a significant resource. This can be useful for tracking views of server-rendered pages before client-side JavaScript takes over, or for tracking views of API resources.

### Syntax [#syntax-1]

```typescript
await rybbit.pageview(payload?: Payload);
```

### Parameters [#parameters]

* **`payload`** (`object`, Optional): An object containing details about the pageview. All properties are optional.
  * `hostname` (`string`): The hostname associated with this pageview.
  * `pathname` (`string`): The path of the page/resource being viewed.
  * `querystring` (`string`): Any query parameters associated with the path.
  * `screenWidth` (`number`): Screen width in pixels.
  * `screenHeight` (`number`): Screen height in pixels.
  * `language` (`string`): Language code.
  * `page_title` (`string`): The title of the page or resource.
  * `referrer` (`string`): The referrer URL.
  * `user_id` (`string`): A unique identifier for the user.
  * `user_agent` (`string`): The user agent string of the client.
  * `ip_address` (`string`): The IP address of the client.

<Callout type="info">
  The fields `screenWidth`, `screenHeight`, `language`, `page_title`, and `referrer` are typically browser-derived. When using the Node.js SDK, you would only provide these if they are relevant and available in your server-side context. For many server-side pageview events, `hostname` and `pathname` might be the most relevant.
</Callout>

### Example [#example-1]

```javascript
// Track a server-rendered page view
async function handleProductPageRequest(req, res) {
  // ... server logic to render product page ...

  await rybbit.pageview({
    hostname: req.hostname,
    pathname: `/products/${req.params.productId}`,
    page_title: `Product - ${product.name}`,
    ip_address: req.ip
  });

  // ... send response ...
}

// Track an API resource view
async function serveApiResource(req) {
  await rybbit.pageview({
    hostname: "api.myservice.com",
    pathname: `/v1/items/${req.params.itemId}`,
    user_id: req.user.id,
    ip_address: req.ip
  });
  // ... return API data ...
}
```

## Tracking Custom Events [#tracking-custom-events]

Use custom events to track specific actions or milestones occurring in your backend system. Examples include user account creation, background job completion, API endpoint usage, or any significant server-side process.

### Syntax [#syntax-2]

```typescript
await rybbit.event(eventName: string, payload?: Payload, properties?: TrackProperties);
```

### Parameters [#parameters-1]

* **`eventName`** (`string`, Required): The name of the event you want to track.
* **`payload`** (`object`, Optional): An object containing contextual details for the event. All properties are optional.
  * `hostname` (`string`): The hostname associated with this event.
  * `pathname` (`string`): The path or resource context for this event.
  * `querystring` (`string`): Any query parameters relevant to the event's context.
  * `screenWidth` (`number`): Screen width in pixels.
  * `screenHeight` (`number`): Screen height in pixels.
  * `language` (`string`): Language code.
  * `page_title` (`string`): The title of the page or resource context.
  * `referrer` (`string`): The referrer URL.
  * `user_id` (`string`): A unique identifier for the user.
  * `user_agent` (`string`): The user agent string of the client.
  * `ip_address` (`string`): The IP address of the client.
* **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values can be a `string`, `number`, `boolean`, or an array of these types.

<Callout type="info">
  The `payload` fields (`hostname`, `pathname`, etc.) provide general context for the event, similar to a pageview. The `properties` object is for data specific to the custom `eventName` itself (e.g., for an `"order_processed"` event, properties might include `orderId: 12345` and `totalAmount: 99.99`).
</Callout>

### Example [#example-2]

```javascript
// Track a new user registration
async function registerUser(userData, req) {
  // ... process user registration ...

  await rybbit.event("user_registered",
    {
      hostname: "auth.myservice.com",
      pathname: "/register",
      ip_address: req.ip
    },
    {
      userId: newUserId,
      registrationMethod: "email"
    }
  );
}

// Track a background job completion
async function processDailyReport(reportId) {
  // ... generate report ...

  await rybbit.event("report_generated",
    {},
    {
      reportId: reportId,
      status: "success",
      processingTimeMs: 12345
    }
  );
}

// Track an API endpoint usage with specific data
async function handleApiRequest(req) {
    // ... handle request ...
    await rybbit.event(
        "api_v1_item_lookup",
        {
          hostname: req.hostname,
          pathname: req.path,
          user_id: req.user.id,
          ip_address: req.ip
        },
        {
          itemId: req.params.itemId,
          clientVersion: req.headers["x-client-version"]
        }
    );
    // ... return response ...
}
```


# React Native (/de/docs/sdks/react-native)





The `@rybbit/react-native` SDK lets you track screens, events, errors, and users in React Native apps. Mobile sites get an App Analytics dashboard mode with mobile-specific labels (e.g. screen views instead of pageviews).

## Creating a Mobile App Site [#creating-a-mobile-app-site]

Before installing the SDK, create a site for your app in the Rybbit dashboard:

1. Click **Add Site** and select the **React Native app** option instead of Website.
2. Enter an app identifier (e.g. `com.example.app`). Letters, numbers, dots, hyphens, and underscores are allowed.
3. Copy the Site ID — you'll pass it to `init()`.

## Installation [#installation]

```bash
npm install @rybbit/react-native @react-native-async-storage/async-storage
```

<Callout type="info">
  `@react-native-async-storage/async-storage` is recommended but not strictly required. The SDK accepts any storage adapter with `getItem`/`setItem`/`removeItem`. Without one, it falls back to in-memory storage and the anonymous visitor ID will not persist across app launches, so every launch counts as a new visitor.
</Callout>

## Initialization [#initialization]

<Callout type="warning">
  `rybbit.init()` **must** be called once before any other tracking methods. Calling other methods first throws an error.
</Callout>

### Syntax [#syntax]

```typescript
async rybbit.init(config: RybbitConfig): Promise<void>;
```

### Example [#example]

```tsx
import AsyncStorage from "@react-native-async-storage/async-storage";
import rybbit from "@rybbit/react-native";

await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  appIdentifier: "com.example.app",
  appVersion: "1.4.2",
  storage: AsyncStorage,
  initialScreenName: "Home",
});
```

### Configuration Options [#configuration-options]

#### Required Options [#required-options]

| Option          | Type               | Description                                                                    |
| :-------------- | :----------------- | :----------------------------------------------------------------------------- |
| `analyticsHost` | `string`           | URL of your Rybbit instance's API (e.g., `https://rybbit.yourdomain.com/api`). |
| `siteId`        | `string \| number` | The Site ID for your app obtained from your Rybbit instance.                   |

#### Optional Options [#optional-options]

| Option                  | Type            | Default     | Description                                                                                                                          |
| :---------------------- | :-------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `appIdentifier`         | `string`        | `""`        | Identifier for your app (e.g., `com.example.app`). Used as the hostname in tracked data. Falls back to `bundleId`, then the site ID. |
| `bundleId`              | `string`        | `""`        | Alias for `appIdentifier`; used when `appIdentifier` is not set.                                                                     |
| `appVersion`            | `string`        | `""`        | Your app's version. Appended to the synthetic user agent sent with each event.                                                       |
| `tag`                   | `string`        | `""`        | A tag added to every event, useful for segmenting data (e.g., by environment or build channel).                                      |
| `storage`               | `RybbitStorage` | in-memory   | Storage adapter used to persist the anonymous visitor ID and identified user ID. Pass `AsyncStorage` or any compatible object.       |
| `storageKeyPrefix`      | `string`        | `"@rybbit"` | Prefix for storage keys. Keys are namespaced per site: `{prefix}:{siteId}:anonymous-id`.                                             |
| `debug`                 | `boolean`       | `false`     | Log SDK warnings (failed requests, config fetch failures) to the console.                                                            |
| `autoTrackAppLifecycle` | `boolean`       | `true`      | Automatically track `app_open` and `app_background` events on `AppState` changes. See [App Lifecycle Events](#app-lifecycle-events). |
| `initialScreenName`     | `string`        | `""`        | If set, a screen view for this name is tracked during `init()` (unless Track Initial Pageview is disabled in your dashboard).        |
| `configTimeoutMs`       | `number`        | `3000`      | Timeout in milliseconds for fetching remote tracking config during `init()`. On timeout or failure, the SDK proceeds with defaults.  |
| `maxQueueSize`          | `number`        | `100`       | Maximum number of failed events kept in the in-memory retry queue. See [Offline Handling](#offline-handling-and-retries).            |
| `fetch`                 | `typeof fetch`  | global      | Custom `fetch` implementation. Defaults to the global `fetch`.                                                                       |

#### Remote Configuration [#remote-configuration]

During `init()`, the SDK fetches your site's tracking settings from the dashboard. Two of them affect the React Native SDK:

| Dashboard Setting      | Effect                                                                     |
| :--------------------- | :------------------------------------------------------------------------- |
| Track Initial Pageview | When disabled, the `initialScreenName` screen view is not tracked on init. |
| Capture Errors         | When disabled, calls to `rybbit.error()` are silently ignored.             |

Web-only settings (session replay, Web Vitals, outbound links, autocapture) do not apply to mobile apps.

## Tracking Screens [#tracking-screens]

Screens are the mobile equivalent of pageviews. Each screen view is tracked with the screen name as both the path and title.

### Syntax [#syntax-1]

```typescript
rybbit.screen(name: string, properties?: TrackProperties, context?: TrackContext): Promise<void>;
```

### Parameters [#parameters]

* **`name`** (`string`, Required): The screen name (e.g., `"Home"`, `"Checkout"`). Used as the pathname (`/Home`) and page title.
* **`properties`** (`object`, Optional): Additional key-value pairs attached to the screen view.
* **`context`** (`object`, Optional): Overrides for the tracked payload. See [Track Context](#track-context).

### Example [#example-1]

```tsx
await rybbit.screen("Checkout");

// With properties and an explicit path
await rybbit.screen("Product", { productId: "sku-123" }, { pathname: "/products/sku-123" });
```

You can also track a raw path directly, mirroring the web SDK:

```typescript
rybbit.pageview(path?: string, context?: TrackContext): Promise<void>;
```

## React Navigation [#react-navigation]

The SDK ships a navigation tracker that hooks into React Navigation's `NavigationContainer` and automatically tracks a screen view whenever the active route changes. Consecutive events for the same route name are deduplicated.

```tsx
import { NavigationContainer, useNavigationContainerRef } from "@react-navigation/native";
import rybbit from "@rybbit/react-native";

const navigationTracker = rybbit.createNavigationTracker();

function App() {
  const navigationRef = useNavigationContainerRef();

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => navigationTracker.onReady(navigationRef)}
      onStateChange={() => navigationTracker.onStateChange(navigationRef)}
    >
      {/* screens */}
    </NavigationContainer>
  );
}
```

### Options [#options]

```typescript
rybbit.createNavigationTracker(options?: NavigationTrackerOptions): NavigationTracker;
```

| Option               | Type                | Default                      | Description                                                                |
| :------------------- | :------------------ | :--------------------------- | :------------------------------------------------------------------------- |
| `includeRouteParams` | `boolean`           | `false`                      | Include the route's params as a `routeParams` property on the screen view. |
| `getRouteName`       | `(route) => string` | `route.name`                 | Customize how the screen name is derived from the current route.           |
| `getPath`            | `(route) => string` | `route.path` or `route.name` | Customize the tracked pathname for the current route.                      |

The returned tracker exposes `onReady`, `onStateChange`, and `trackCurrentRoute` — all take the navigation ref and track the current route if it changed. It works with any navigation library whose ref exposes a `getCurrentRoute()` method.

<Callout type="warning">
  Route params can contain sensitive data (IDs, tokens, emails). Only enable `includeRouteParams` if your route params are safe to store in analytics.
</Callout>

## Tracking Custom Events [#tracking-custom-events]

### Syntax [#syntax-2]

```typescript
rybbit.event(name: string, properties?: TrackProperties, context?: TrackContext): Promise<void>;
```

### Parameters [#parameters-1]

* **`name`** (`string`, Required): The name of the event you want to track.
* **`properties`** (`object`, Optional): Additional key-value pairs related to the event.

### Example [#example-2]

```tsx
await rybbit.event("signup_started", { plan: "pro" });

await rybbit.event("purchase_completed", {
  orderId: "order-123",
  total: 49.99,
  currency: "USD",
});
```

## Error Tracking [#error-tracking]

Capture handled errors with additional context. Error tracking must be enabled in your Rybbit dashboard (Capture Errors) — when disabled, `error()` calls are ignored.

### Syntax [#syntax-3]

```typescript
rybbit.error(error: Error | unknown, properties?: TrackProperties, context?: TrackContext): Promise<void>;
```

Non-`Error` values are converted to an `Error`. The message is truncated to 500 characters and the stack trace to 2,000.

### Example [#example-3]

```tsx
try {
  await processPayment(order);
} catch (error) {
  await rybbit.error(error, { component: "checkout", orderId: order.id });
  showErrorMessage();
}
```

<Callout type="info">
  Unlike the web SDK, the React Native SDK does not automatically capture uncaught exceptions — wrap the code you care about and call `rybbit.error()` yourself.
</Callout>

## User Identification [#user-identification]

Associate events with a user ID and optional traits. The ID is persisted through the configured storage adapter and attached to all subsequent events.

```typescript
rybbit.identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
rybbit.setTraits(traits: Record<string, unknown>): Promise<void>;
rybbit.clearUserId(): Promise<void>;
rybbit.getUserId(): string | null;
```

```tsx
// After login
await rybbit.identify("user_123", { plan: "pro", signupDate: "2026-01-15" });

// Update traits later without changing the ID
await rybbit.setTraits({ plan: "enterprise" });

// After logout
await rybbit.clearUserId();
```

<Callout type="info">
  `setTraits()` throws if no user has been identified yet — call `identify()` first.
</Callout>

## App Lifecycle Events [#app-lifecycle-events]

With `autoTrackAppLifecycle` enabled (the default), the SDK listens to React Native's `AppState` and tracks:

* **`app_open`** — when the app launches in the foreground or returns to the foreground from the background.
* **`app_background`** — when the app leaves the foreground, with a `state` property (`"background"` or `"inactive"`).

Set `autoTrackAppLifecycle: false` in `init()` to disable these events.

## Offline Handling and Retries [#offline-handling-and-retries]

Events that fail to send (e.g., no network) are kept in an in-memory queue, capped at `maxQueueSize` (default 100, oldest dropped first). Queued events are retried when `init()` completes and whenever you call:

```typescript
rybbit.flush(): Promise<void>;
```

<Callout type="warning">
  The retry queue is in-memory only — events still queued when the app is killed are lost.
</Callout>

## Track Context [#track-context]

All tracking methods accept an optional `context` object to override what's sent with that event:

| Field           | Type     | Description                                   |
| :-------------- | :------- | :-------------------------------------------- |
| `appIdentifier` | `string` | Override the hostname for this event.         |
| `pathname`      | `string` | Override the tracked path.                    |
| `querystring`   | `string` | Query string to attach to the event.          |
| `screen`        | `string` | Screen name, used as the path/title fallback. |
| `title`         | `string` | Override the page title.                      |
| `referrer`      | `string` | Referrer value (empty by default on mobile).  |
| `language`      | `string` | Override the detected device locale.          |
| `userAgent`     | `string` | Override the synthetic user agent.            |

Device locale, screen dimensions, and a platform-appropriate user agent (including your `appVersion`) are detected automatically.

## Cleanup [#cleanup]

Removes the `AppState` lifecycle listener. Call it if you tear down the SDK, e.g. in tests or when unmounting your app root.

```typescript
rybbit.cleanup(): void;
```

## Differences from the Web SDK [#differences-from-the-web-sdk]

* **Session replay** and **Web Vitals** are web-only and not available for React Native apps.
* No automatic outbound link, button click, form, or copy tracking (there is no DOM).
* Uncaught errors are not captured automatically — use `rybbit.error()` in your own error boundaries and catch blocks.
* The anonymous visitor ID is generated by the SDK and persisted via your storage adapter, rather than derived from browser fingerprinting.


# JavaScript (Web) (/de/docs/sdks/web)





## Installation [#installation]

```bash
npm install @rybbit/js
```

```bash
yarn add @rybbit/js
```

## Peer Dependencies [#peer-dependencies]

The SDK has an optional peer dependency for session replay functionality:

```bash
npm install rrweb
```

```bash
yarn add rrweb
```

<Callout type="info">
  The `rrweb` package is only required if you enable session replay in your Rybbit dashboard. The SDK will work without it for all other tracking features.
</Callout>

## Initialization [#initialization]

<Callout type="warning">
  `rybbit.init()` **must** be called once before any other tracking methods (`pageview`, `event`, etc.) can be used. Attempting to call other methods before `init` will result in errors or no tracking.
</Callout>

### Syntax [#syntax]

```typescript
async rybbit.init(config: RybbitConfig): Promise<void>;
```

### Example [#example]

```javascript
import rybbit from "@rybbit/js";

await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
});
```

### Configuration Options [#configuration-options]

#### Required Options [#required-options]

| Option          | Type     | Description                                                                        |
| :-------------- | :------- | :--------------------------------------------------------------------------------- |
| `analyticsHost` | `string` | URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |
| `siteId`        | `string` | The Site ID for your website obtained from your Rybbit instance.                   |

#### Local Configuration Options [#local-configuration-options]

These options are configured in your code and control SDK behavior locally:

| Option                | Type       | Default | Description                                                                                                                                                             |
| :-------------------- | :--------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `debounceDuration`    | `number`   | `500`   | Debounce time in milliseconds for tracking pageviews after route changes. Set to `0` to disable debouncing (track immediately).                                         |
| `skipPatterns`        | `string[]` | `[]`    | Array of path patterns. Pageviews whose path matches any pattern will **not** be tracked. See [Path Matching](#path-matching).                                          |
| `maskPatterns`        | `string[]` | `[]`    | Array of path patterns. For matching pageview paths, the original path will be **replaced** by the pattern itself in tracked data. See [Path Matching](#path-matching). |
| `debug`               | `boolean`  | `false` | Enable detailed logging to the browser console.                                                                                                                         |
| `replayPrivacyConfig` | `object`   | -       | Privacy settings for session replay. See [Session Replay](#session-replay).                                                                                             |

#### Remote Configuration [#remote-configuration]

These settings are controlled through your Rybbit dashboard and cannot be set in the init config:

| Dashboard Setting       | Description                                              | Default |
| :---------------------- | :------------------------------------------------------- | :------ |
| Track Initial Pageview  | Track pageview on initial page load                      | `true`  |
| Track SPA Navigation    | Track pageviews on Single Page Application route changes | `true`  |
| Track URL Parameters    | Include URL query strings in tracked data                | `true`  |
| Track Outbound Links    | Automatically track clicks on external links             | `true`  |
| Track Web Vitals        | Track Core Web Vitals performance metrics                | `false` |
| Capture Errors          | Enable automatic error tracking                          | `false` |
| Session Replay          | Enable session replay recording                          | `false` |
| Track Button Clicks     | Automatically track button click interactions            | `false` |
| Track Copy              | Automatically track copy events                          | `false` |
| Track Form Interactions | Automatically track form submissions and input changes   | `false` |

If fetching settings fails or times out, the SDK uses sensible defaults.

## Tracking Pageviews [#tracking-pageviews]

Pageviews are tracked automatically based on your dashboard settings. This includes the initial page load and subsequent route changes in Single Page Applications (SPAs).

### Syntax [#syntax-1]

```typescript
rybbit.pageview(path?: string);
```

### Parameters [#parameters]

* **`path`** (`string`, Optional):
  * Replaces the detected URL path (`window.location.pathname`) and query string (`window.location.search`) for this specific pageview event.
  * Should start with a `/` (e.g., `/virtual/my-custom-page`).
  * If `path` includes its own query string (e.g., `/virtual/step?id=123`), that query string will be used for the event. If `path` has no query string, the `querystring` property will be empty.
  * `skipPatterns` and `maskPatterns` will be applied to `path`.

### When to Use Manually [#when-to-use-manually]

* **Automatic tracking disabled:** If you disabled automatic pageview tracking in your dashboard.
* **Virtual Pageviews:** In SPAs where a significant view change occurs without a URL change.
* **Specific Timing:** If you need to ensure a pageview is tracked only after certain conditions are met.

### Example [#example-1]

```javascript
// Standard manual pageview (usually not needed if auto-tracking is on)
rybbit.pageview();

// Example: Track a step within a multi-step modal
function openUserDetailsModal(userId, step) {
  // ... logic to open and display the modal step ...
  rybbit.pageview(`/users/${userId}/modal/${step}`);
}
openUserDetailsModal("user-abc", "contact-info");

// Example: Track a virtual pageview with its own query parameters
function showFilteredProductList(category, sortBy) {
   let virtualPathWithQuery = `/products/category/${category}?sort=${sortBy}&view=grid`;
   rybbit.pageview(virtualPathWithQuery);
}
showFilteredProductList("electronics", "price_desc");
```

## Tracking Custom Events [#tracking-custom-events]

Use custom events to track specific user interactions. Examples include button clicks, form submissions, or adding an item to a cart.

### Programmatic Tracking [#programmatic-tracking]

You can trigger events from your JavaScript code.

#### Syntax [#syntax-2]

```typescript
rybbit.event(name: string, properties?: TrackProperties);
```

#### Parameters [#parameters-1]

* **`name`** (`string`, Required): The name of the event you want to track.
* **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values can be a `string`, `number`, `boolean`, or an array of these types.

#### Example [#example-2]

```javascript
// Track a simple button click
document.getElementById("cta-button")?.addEventListener("click", () => {
  rybbit.event("cta_click");
});

// Track adding an item to a shopping cart with properties
function addToCart(item) {
  // ... add item ...
  rybbit.event("add_to_cart", {
    itemId: item.id,
    itemName: item.name,
    price: item.price,
    quantity: 1
  });
}
```

### Declarative Tracking with Data Attributes [#declarative-tracking-with-data-attributes]

The SDK automatically listens for clicks on elements with the `data-rybbit-event` attribute.

* `data-rybbit-event="<event-name>"`: This attribute makes the element trackable. The value is used as the event name.
* `data-rybbit-prop-<property-name>="<value>"`: You can add multiple properties to the event by using this attribute format. The SDK collects all attributes starting with `data-rybbit-prop-` and includes them as key-value pairs in the event data.

#### Example [#example-3]

```html
<button data-rybbit-event="cta_click">Click Me</button>

<button
  data-rybbit-event="add_to_cart"
  data-rybbit-prop-item_id="product-123"
  data-rybbit-prop-item_name="Classic T-Shirt"
  data-rybbit-prop-price="29.99"
>
  Add to Cart
</button>
```

## Tracking Outbound Links [#tracking-outbound-links]

Outbound links (links to external domains) are tracked automatically by default based on your dashboard settings. The SDK attaches a global click listener to capture clicks on `<a>` tags with external `href` attributes.

### Syntax [#syntax-3]

```typescript
rybbit.trackOutbound(url: string, text?: string, target?: string);
```

### Parameters [#parameters-2]

* **`url`** (`string`, Required): The destination URL of the outbound link.
* **`text`** (`string`, Optional): The text content of the link. Defaults to `""`.
* **`target`** (`string`, Optional): The `target` attribute of the link (e.g., `_blank`). Defaults to `_self`.

### When to Use Manually [#when-to-use-manually-1]

* **Automatic tracking disabled:** If you disabled outbound link tracking in your dashboard.
* **Non-anchor elements:** If you trigger navigation to an external site using JavaScript from an element that isn't an `<a>` tag.

### Example [#example-4]

```javascript
// Manually track an outbound click triggered by a button
document.getElementById("external-service-button")?.addEventListener("click", () => {
  let url = "https://external-service.com";
  rybbit.trackOutbound(url, "Visit External Service", "_blank");
  // Optionally navigate after tracking
  window.open(url, "_blank");
});
```

## Error Tracking [#error-tracking]

The SDK can automatically capture JavaScript errors and unhandled promise rejections. This feature must be enabled in your Rybbit dashboard.

### Automatic Error Capture [#automatic-error-capture]

When enabled in your dashboard, the SDK will automatically track:

* Uncaught exceptions (`window.error` events)
* Unhandled promise rejections (`window.unhandledrejection` events)

### Manual Error Capture [#manual-error-capture]

You can manually capture errors with additional context:

#### Syntax [#syntax-4]

```typescript
rybbit.error(error: Error | ErrorEvent, context?: TrackProperties);
```

#### Parameters [#parameters-3]

* **`error`** (`Error | ErrorEvent`, Required): The error object to capture.
* **`context`** (`object`, Optional): Additional context to include with the error.

#### Example [#example-5]

```javascript
try {
  // Some risky operation
  processPayment(orderData);
} catch (error) {
  rybbit.error(error, {
    component: "checkout",
    orderId: "order-123",
    userId: currentUser.id
  });
  // Handle error in your UI
  showErrorMessage("Payment failed");
}

// Capture error from async operation
async function fetchUserData(userId) {
  try {
    const response = await fetch(`/api/users/${userId}`);
    return await response.json();
  } catch (error) {
    rybbit.error(error, {
      endpoint: "/api/users",
      userId: userId
    });
    throw error;
  }
}
```

<Callout type="info">
  Manual error capture only works when error tracking is enabled in your dashboard settings. If it's disabled, calling `error()` will log a warning.
</Callout>

## Session Replay [#session-replay]

Session replay records user interactions on your website, allowing you to watch how users navigate and interact with your site. This feature requires the `rrweb` peer dependency.

### Installation [#installation-1]

```bash
npm install rrweb
```

### Enabling Session Replay [#enabling-session-replay]

Session replay must be enabled in your Rybbit dashboard under. Once enabled, recording starts automatically when the SDK initializes.

### Manual Controls [#manual-controls]

You can manually start, stop, and check the status of session replay:

```typescript
// Start recording (only works if enabled in dashboard)
rybbit.startSessionReplay();

// Stop recording
rybbit.stopSessionReplay();

// Check if currently recording
const isRecording = rybbit.isSessionReplayActive();
if (isRecording) {
  console.log("Session is being recorded");
}
```

### Privacy Configuration [#privacy-configuration]

Session replay includes privacy-focused defaults and configuration options:

```javascript
await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  replayPrivacyConfig: {
    maskAllInputs: true, // Mask all input values (default: true)
    maskTextSelectors: [
      ".sensitive-data",  // Mask text in elements with this class
      "#credit-card"      // Mask specific element IDs
    ]
  }
});
```

#### Privacy Config Options [#privacy-config-options]

| Option              | Type                | Description                                                             |
| :------------------ | :------------------ | :---------------------------------------------------------------------- |
| `maskAllInputs`     | `boolean`           | Mask all input values (default: `true`)                                 |
| `maskTextSelectors` | `string[]`          | CSS selectors for elements whose text should be masked                  |
| `blockClass`        | `string`            | CSS class name to block elements from recording (default: `rr-block`)   |
| `blockSelector`     | `string`            | CSS selector to block elements from recording                           |
| `ignoreClass`       | `string`            | CSS class name to ignore elements from recording (default: `rr-ignore`) |
| `ignoreSelector`    | `string`            | CSS selector to ignore elements from recording                          |
| `maskTextClass`     | `string`            | CSS class name to mask text content (default: `rr-mask`)                |
| `collectFonts`      | `boolean`           | Whether to collect font information (default: `true`)                   |
| `slimDOMOptions`    | `object \| boolean` | Options to reduce DOM snapshot size                                     |

## User Identification [#user-identification]

You can associate tracking events with a specific user ID and optional traits. The ID is persisted in `localStorage` and will be attached to all subsequent tracking events for that user.

### `identify` [#identify]

Assigns a user ID with optional traits.

```typescript
rybbit.identify(userId: string, traits?: Record<string, unknown>);
```

**Parameters:**

* **`userId`** (`string`, Required): The user ID to associate with tracking events.
* **`traits`** (`object`, Optional): An object containing user attributes/properties.

**Example:**

```javascript
// After a user logs in
rybbit.identify("user-xzy-123");

// With traits
rybbit.identify("user-xzy-123", {
  email: "user@example.com",
  plan: "premium",
  signupDate: "2024-01-15"
});
```

### `setTraits` [#settraits]

Updates traits for the currently identified user without changing the user ID.

```typescript
rybbit.setTraits(traits: Record<string, unknown>);
```

**Example:**

```javascript
// Update user traits after they upgrade
rybbit.setTraits({
  plan: "enterprise",
  upgradeDate: "2024-03-01"
});
```

### `clearUserId` [#clearuserid]

Clears the stored user ID.

```typescript
rybbit.clearUserId();
```

**Example:**

```javascript
// When a user logs out
rybbit.clearUserId();
```

### `getUserId` [#getuserid]

Retrieves the currently stored user ID.

```typescript
rybbit.getUserId(): string | null;
```

**Example:**

```javascript
let currentUserId = rybbit.getUserId();
console.log("Current Rybbit User ID:", currentUserId);
```

## Page Change Callbacks [#page-change-callbacks]

Register callbacks that execute when the page or route changes. This is useful for integrating with third-party tools or triggering custom logic on navigation.

### Syntax [#syntax-5]

```typescript
rybbit.onPageChange(callback: (newPath: string, previousPath: string) => void): () => void;
```

### Parameters [#parameters-4]

* **`callback`** (`function`, Required): Function to execute on page change. Receives:
  * `newPath`: The new pathname
  * `previousPath`: The previous pathname

### Returns [#returns]

Returns an unsubscribe function to remove the callback.

### Example [#example-6]

```javascript
// Register a callback
const unsubscribe = rybbit.onPageChange((newPath, previousPath) => {
  console.log(`Navigated from ${previousPath} to ${newPath}`);

  // Example: Track scroll position reset
  window.scrollTo(0, 0);
});

// Later, to remove the callback
unsubscribe();

// Example: Multiple callbacks can be registered
rybbit.onPageChange((newPath) => {
  // Update page title
  document.title = `${newPath} - My Site`;
});

rybbit.onPageChange((newPath, previousPath) => {
  // Log navigation for debugging
  if (process.env.NODE_ENV === 'development') {
    console.log('Navigation:', { from: previousPath, to: newPath });
  }
});
```

<Callout type="info">
  Callbacks are only triggered when the pathname actually changes. Multiple calls to the same path won't trigger callbacks repeatedly.
</Callout>

## Opting Out [#opting-out]

Users can opt out of all tracking by setting a flag in `localStorage` or on the `window` object. When opted out, all tracking calls are silently ignored.

```javascript
// Opt out via localStorage (persists across sessions)
localStorage.setItem("disable-rybbit", "true");

// Opt out via window flag (current session only)
window.__RYBBIT_OPTOUT__ = true;
```

To re-enable tracking, remove the localStorage item and reload the page:

```javascript
localStorage.removeItem("disable-rybbit");
```

## Cleanup [#cleanup]

In Single Page Applications or other dynamic environments, you may need to manually clean up the listeners that the SDK sets up.

### Syntax [#syntax-6]

```typescript
rybbit.cleanup();
```

### What Gets Cleaned Up [#what-gets-cleaned-up]

* SPA route change listeners (`popstate`, `hashchange`)
* Outbound link click listeners
* Data attribute click listeners
* Error tracking listeners
* Session replay recording
* Page change callbacks
* Resets initialization state

### Example [#example-7]

```javascript
// In React
useEffect(() => {
  rybbit.init({
    analyticsHost: "https://app.rybbit.io/api",
    siteId: "1",
  });

  return () => {
    rybbit.cleanup();
  };
}, []);
```

## Path Matching [#path-matching]

These options allow you to control which page paths are tracked and how they appear in your analytics data using wildcard patterns.

### Wildcards [#wildcards]

* `*`: Matches any sequence of characters **except** the forward slash (`/`). Useful for matching single path segments.
* `**`: Matches any sequence of characters **including** the forward slash (`/`). Useful for matching multiple path segments.

### Regex Patterns [#regex-patterns]

For more advanced matching, you can use raw regular expressions by prefixing the pattern with `re:`:

```javascript
skipPatterns: [
  "re:^/users/\\d+/profile$",  // Match numeric user IDs only
  "re:^/api/v[0-9]+/"          // Match any API version prefix
]
```

### `skipPatterns` [#skippatterns]

If a page's path matches any pattern in `skipPatterns`, the pageview for that path will **not** be sent.

**Examples:**

* `"/admin/*"`: Skips `/admin/login`, `/admin/users`, but **not** `/admin/settings/profile`.
* `"/admin/**"`: Skips `/admin/login`, `/admin/users`, *and* `/admin/settings/profile`.
* `"/users/*/profile"`: Skips `/users/123/profile`, `/users/abc/profile`, but **not** `/users/123/settings`.

```javascript
// Example skipPatterns in init
await rybbit.init({
  // ... other options
  skipPatterns: [
    "/admin/**",        // Skip all admin sections
    "/debug",           // Skip exact /debug path
    "/users/*/settings" // Skip settings page for any user
  ]
});
```

### `maskPatterns` [#maskpatterns]

If a page's path matches a pattern in `maskPatterns`, the pageview **will** be sent, but the `pathname` will be **replaced** by the pattern string itself. This is useful for grouping similar pages or hiding sensitive IDs.

<Callout type="warning">
  If a path matches both a `skipPatterns` and a `maskPatterns` pattern, **skipping takes priority**.
</Callout>

**Examples:**

* Pattern: `"/users/*/profile"`
  * `/users/123/profile` is tracked as `pathname: "/users/*/profile"`.
* Pattern: `"/products/**"`
  * `/products/electronics/tv-123` is tracked as `pathname: "/products/**"`.

```javascript
// Example maskPatterns in init
await rybbit.init({
  // ... other options
  maskPatterns: [
    "/users/*/profile",  // Group all user profile views
    "/orders/*"          // Mask specific order IDs
  ]
});
```


# Custom Nginx setup (/de/docs/self-hosting-guides/custom-nginx)





This guide shows you how to set up Rybbit with your own Nginx installation instead of using the built-in Caddy server.

## Prerequisites [#prerequisites]

* Existing Nginx installation
* SSL certificates (Let's Encrypt recommended)
* Domain pointed to your server
* Rybbit running with `--no-webserver` flag

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Run Rybbit without Caddy [#run-rybbit-without-caddy]

    First, set up Rybbit to expose ports without the built-in webserver:

    ```bash
    ./setup.sh your.domain.name --no-webserver
    ```

    Optionally, include a Mapbox token for globe visualizations:

    ```bash
    ./setup.sh your.domain.name --no-webserver --mapbox-token YOUR_MAPBOX_TOKEN
    ```

    This will expose:

    * Backend service on port 3001
    * Client service on port 3002
  </Step>

  <Step>
    ### Configure Nginx [#configure-nginx]

    Create or update your Nginx configuration file (usually in `/etc/nginx/sites-available/`):

    ```nginx
    server {
        listen 80;
        server_name your.domain.name;
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name your.domain.name;

        # SSL configuration (using Let's Encrypt)
        ssl_certificate /etc/letsencrypt/live/your.domain.name/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/your.domain.name/privkey.pem;
        
        # Modern SSL configuration
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
        ssl_prefer_server_ciphers off;
        
        # Security headers
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-XSS-Protection "1; mode=block" always;

        # Backend service
        location ~ ^/(api|\.well-known)/.*$ {
            proxy_pass http://localhost:3001;
            proxy_set_header Host $host;
            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_set_header X-Forwarded-Host $server_name;
            
            # Timeouts
            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
        }

        # Client service
        location / {
            proxy_pass http://localhost:3002;
            proxy_set_header Host $host;
            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_set_header X-Forwarded-Host $server_name;
            
            # Timeouts
            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
        }
    }
    ```
  </Step>

  <Step>
    ### Enable the Site [#enable-the-site]

    Enable your Nginx configuration:

    ```bash
    # Create symlink to enable the site
    sudo ln -s /etc/nginx/sites-available/your-site /etc/nginx/sites-enabled/

    # Test the configuration
    sudo nginx -t

    # Reload Nginx
    sudo systemctl reload nginx
    ```
  </Step>

  <Step>
    ### Verify Setup [#verify-setup]

    Check that everything is working:

    ```bash
    # Check Nginx status
    sudo systemctl status nginx

    # Check Rybbit services
    docker compose ps

    # Test the website
    curl -I https://your.domain.name
    ```
  </Step>
</Steps>

## SSL Certificate Setup with Certbot [#ssl-certificate-setup-with-certbot]

If you need to set up SSL certificates with Let's Encrypt:

<Steps>
  <Step>
    ### Install Certbot [#install-certbot]

    ```bash
    # Ubuntu/Debian
    sudo apt update
    sudo apt install certbot python3-certbot-nginx

    # CentOS/RHEL
    sudo yum install certbot python3-certbot-nginx
    ```
  </Step>

  <Step>
    ### Obtain Certificate [#obtain-certificate]

    ```bash
    sudo certbot --nginx -d your.domain.name
    ```
  </Step>

  <Step>
    ### Auto-renewal [#auto-renewal]

    Set up automatic renewal:

    ```bash
    # Test renewal
    sudo certbot renew --dry-run

    # Check existing cron job
    sudo crontab -l
    ```

    Certbot usually sets up auto-renewal automatically, but you can add this cron job if needed:

    ```bash
    0 12 * * * /usr/bin/certbot renew --quiet
    ```
  </Step>
</Steps>

## Custom Ports [#custom-ports]

If you need to use custom ports for Rybbit:

```bash
./setup.sh your.domain.name --no-webserver --backend-port 8080 --client-port 8081

# With Mapbox token
./setup.sh your.domain.name --no-webserver --backend-port 8080 --client-port 8081 --mapbox-token YOUR_MAPBOX_TOKEN
```

Update your Nginx configuration accordingly:

```nginx
location /api/ {
    proxy_pass http://localhost:8080;  # Custom backend port
    # ... rest of config
}

location / {
    proxy_pass http://localhost:8081;  # Custom client port
    # ... rest of config
}
```

## Troubleshooting [#troubleshooting]

### Common Issues [#common-issues]

**502 Bad Gateway**: Check if Rybbit services are running:

```bash
docker compose ps
docker compose logs
```

**SSL Certificate Issues**: Verify certificate paths:

```bash
sudo certbot certificates
```

**Permission Denied**: Check Nginx error logs:

```bash
sudo tail -f /var/log/nginx/error.log
```

### Logs [#logs]

Monitor logs for debugging:

```bash
# Nginx access logs
sudo tail -f /var/log/nginx/access.log

# Nginx error logs
sudo tail -f /var/log/nginx/error.log

# Rybbit logs
docker compose logs -f
```


# Nginx Proxy Manager (NPM) setup (/de/docs/self-hosting-guides/nginx-proxy-manager)





This guide shows you how to set up Rybbit with Nginx Proxy Manager without exposing ports directly to the host.

## Prerequisites [#prerequisites]

* [Nginx Proxy Manager](https://nginxproxymanager.com) already running
* Basic knowledge of Docker networks
* Domain name pointed to your server

<Callout type="info">
  This setup assumes you have NPM running and are capable of creating SSL certificates. You can also use any other reverse proxy as long as you can put it on the same Docker network as Rybbit.
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Create Custom Docker Compose [#create-custom-docker-compose]

    Create a new directory for your Rybbit installation and create a `docker-compose.yml` file:

    ```yaml
    services:
      rybbit_clickhouse:
        image: clickhouse/clickhouse-server:26.3.17.4
        container_name: rybbit_clickhouse
        volumes:
          - ./clickhouse-data:/var/lib/clickhouse
        configs:
          - source: clickhouse_network
            target: /etc/clickhouse-server/config.d/network.xml
          - source: clickhouse_logging
            target: /etc/clickhouse-server/config.d/logging_rules.xml
          # Profile (user-level) settings are only read from users.d, not config.d
          - source: clickhouse_user_settings
            target: /etc/clickhouse-server/users.d/user_settings.xml
        environment:
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        networks:
          - internal

      rybbit_postgres:
        image: postgres:17.4
        container_name: rybbit_postgres
        environment:
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
        volumes:
          - ./postgres-data:/var/lib/postgresql/data
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        networks:
          - internal

      rybbit_redis:
        image: redis:8.6.4-alpine
        container_name: rybbit_redis
        volumes:
          - ./redis-data:/data
        healthcheck:
          test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 5s
        restart: unless-stopped
        command:
          - redis-server
          - --requirepass
          - ${REDIS_PASSWORD:-changeme}
          - --appendonly
          - "yes"
          - --appendfsync
          - everysec
          - --maxmemory-policy
          - noeviction
        networks:
          - internal

      rybbit_backend:
        image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}
        container_name: rybbit_backend
        environment:
          - NODE_ENV=production
          - CLICKHOUSE_HOST=http://rybbit_clickhouse:8123
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
          - POSTGRES_HOST=rybbit_postgres
          - POSTGRES_PORT=5432
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - REDIS_HOST=rybbit_redis
          - REDIS_PORT=6379
          - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
          - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
          - BASE_URL=${BASE_URL}
          - DISABLE_SIGNUP=${DISABLE_SIGNUP}
          - MAPBOX_TOKEN=${MAPBOX_TOKEN}
        depends_on:
          rybbit_clickhouse:
            condition: service_healthy
          rybbit_postgres:
            condition: service_healthy
          rybbit_redis:
            condition: service_healthy
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3001/api/health"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        networks:
          - internal
          - npm_proxy

      rybbit_client:
        image: ghcr.io/rybbit-io/rybbit-client:${IMAGE_TAG:-latest}
        container_name: rybbit_client
        environment:
          - NODE_ENV=production
          - NEXT_PUBLIC_BACKEND_URL=${BASE_URL}
          - NEXT_PUBLIC_DISABLE_SIGNUP=${DISABLE_SIGNUP}
        depends_on:
          - rybbit_backend
        restart: unless-stopped
        networks:
          - internal
          - npm_proxy

    networks:
      internal:
        driver: bridge
      npm_proxy:
        external: true

    configs:
      clickhouse_network:
        content: |
          <clickhouse>
              <listen_host>0.0.0.0</listen_host>
          </clickhouse>

      clickhouse_logging:
        content: |
          <clickhouse>
            <logger>
                <level>warning</level>
                <console>true</console>
            </logger>
            <query_thread_log remove="remove"/>
            <query_log remove="remove"/>
            <text_log remove="remove"/>
            <trace_log remove="remove"/>
            <metric_log remove="remove"/>
            <asynchronous_metric_log remove="remove"/>
            <session_log remove="remove"/>
            <part_log remove="remove"/>
            <latency_log remove="remove"/>
            <processors_profile_log remove="remove"/>
          </clickhouse>

      clickhouse_user_settings:
        content: |
          <clickhouse>
            <profiles>
              <default>
                <enable_json_type>1</enable_json_type>
                <!-- 26.3+ enables async_insert by default; the backend already
                     batches app-side, so keep inserts synchronous -->
                <async_insert>0</async_insert>
                <log_queries>0</log_queries>
                <log_query_threads>0</log_query_threads>
                <log_processors_profiles>0</log_processors_profiles>
              </default>
            </profiles>
          </clickhouse>
    ```
  </Step>

  <Step>
    ### Configure Environment [#configure-environment]

    Create a `.env` file in the same directory:

    ```bash
    # Required: Your domain and base URL
    DOMAIN_NAME=your.domain.com
    BASE_URL=https://your.domain.com

    # Required: Authentication secret (generate a random 32+ character string)
    BETTER_AUTH_SECRET=your_generated_secret_here

    # Optional: Disable new user signups after creating admin account
    DISABLE_SIGNUP=false

    # Optional but recommended: Mapbox token for globe visualizations
    MAPBOX_TOKEN=your_mapbox_token

    # Optional: Custom image tag
    IMAGE_TAG=latest
    ```

    <Callout type="info">
      Generate a secure `BETTER_AUTH_SECRET` using: `openssl rand -hex 32`
    </Callout>
  </Step>

  <Step>
    ### Setup Docker Network [#setup-docker-network]

    Create the external network that NPM uses (if it doesn't exist):

    ```bash
    docker network create npm_proxy
    ```

    Make sure your NPM container is connected to this network:

    ```bash
    # Check if NPM is on the network
    docker network inspect npm_proxy

    # If needed, connect NPM to the network
    docker network connect npm_proxy <npm_container_name>
    ```
  </Step>

  <Step>
    ### Start Services [#start-services]

    Start all Rybbit services:

    ```bash
    docker compose up -d
    ```

    Verify all services are running:

    ```bash
    docker compose ps
    ```
  </Step>

  <Step>
    ### Configure NPM [#configure-npm]

    In your Nginx Proxy Manager interface:

    1. **Create Proxy Host**:
       * Domain Names: `your.domain.com`
       * Scheme: `http`
       * Forward Hostname/IP: `rybbit_client`
       * Forward Port: `3002`
       * Enable "Cache Assets", "Block Common Exploits", "Websockets Support"

    2. **Add Custom Location**:
       * Location: `/api`
       * Scheme: `http`
       * Forward Hostname/IP: `rybbit_backend`
       * Forward Port: `3001`

    3. **Advanced Configuration** (in the custom location):
       ```nginx
       location /api/ {
           proxy_pass http://rybbit_backend:3001;
           proxy_set_header Host $host;
           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;
       }
       ```

    4. **SSL Configuration**:
       * Enable SSL
       * Request a new SSL certificate with Let's Encrypt
       * Enable "Force SSL" and "HTTP/2 Support"
  </Step>

  <Step>
    ### Access Rybbit [#access-rybbit]

    Navigate to `https://your.domain.com` and create your admin account.
  </Step>
</Steps>

## Alternative Proxy Configurations [#alternative-proxy-configurations]

### Traefik [#traefik]

If you're using Traefik instead, add these labels to your services:

```yaml
services:
  rybbit_backend:
    # ... existing config
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && PathPrefix(`/api`)"
      - "traefik.http.routers.rybbit-api.tls.certresolver=letsencrypt"
      - "traefik.http.services.rybbit-api.loadbalancer.server.port=3001"
      - "traefik.docker.network=traefik_proxy"
  
  rybbit_client:
    # ... existing config
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.rybbit-client.rule=Host(`your.domain.com`)"
      - "traefik.http.routers.rybbit-client.tls.certresolver=letsencrypt"
      - "traefik.http.services.rybbit-client.loadbalancer.server.port=3002"
      - "traefik.docker.network=traefik_proxy"

networks:
  traefik_proxy:
    external: true
```

### Cloudflare Tunnel [#cloudflare-tunnel]

For Cloudflare Tunnel, create a tunnel configuration:

```yaml
tunnel: your-tunnel-id
credentials-file: /path/to/credentials.json

ingress:
  - hostname: your.domain.com
    path: /api
    service: http://rybbit_backend:3001
  - hostname: your.domain.com
    service: http://rybbit_client:3002
  - service: http_status:404
```

## Troubleshooting [#troubleshooting]

### Common Issues [#common-issues]

**NPM can't reach containers**:

* Verify both NPM and Rybbit are on the same network
* Check container names match the proxy configuration

**SSL certificate issues**:

* Ensure domain is pointed to your server
* Check NPM logs for certificate generation errors

**502 Bad Gateway**:

* Verify Rybbit services are healthy: `docker compose ps`
* Check container logs: `docker compose logs`

### Networking [#networking]

Check network connectivity:

```bash
# List all networks
docker network ls

# Inspect the npm_proxy network
docker network inspect npm_proxy

# Check which containers are connected
docker ps --format "table {{.Names}}\t{{.Networks}}"
```

### Logs [#logs]

Monitor logs for debugging:

```bash
# Rybbit services
docker compose logs -f

# Specific service
docker compose logs -f rybbit_backend

# NPM logs (adjust container name)
docker logs -f nginx-proxy-manager
```

<Callout type="warning">
  Remember to regularly backup your data volumes (`clickhouse-data` and `postgres-data`) and your `.env` file.
</Callout>


# Pangolin setup (/de/docs/self-hosting-guides/pangolin)







This guide shows you how to set up Rybbit with [Pangolin](https://github.com/fosrl/pangolin), a self-hosted reverse proxy, using a Newt container inside the Docker Compose stack. This approach avoids exposing ports directly on your host network.

## Prerequisites [#prerequisites]

* [Pangolin](https://github.com/fosrl/pangolin) already running and accessible (e.g. `https://pangolin.yourdomain.com`)
* A Newt ID and Newt Secret from your Pangolin instance
* A domain name pointed to your Pangolin server (e.g. `tracking.yourdomain.com`)
* Docker and Docker Compose installed

<Callout type="warning">
  You **must** generate a proper `BETTER_AUTH_SECRET` before starting. Without a valid 32+ character secret, you will not be able to create organizations or log in. Generate one with: `openssl rand -hex 32`
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Configure Environment Variables [#configure-environment-variables]

    Create a `.env` file in your Rybbit directory:

    ```bash
    # Required: Your domain and base URL
    DOMAIN_NAME=tracking.yourdomain.com
    BASE_URL=https://tracking.yourdomain.com

    # Required: Authentication secret (must be 32+ characters)
    # Generate with: openssl rand -hex 32
    BETTER_AUTH_SECRET=your_generated_secret_here

    # Required: Disable built-in webserver since Pangolin handles routing
    USE_WEBSERVER=false

    # ClickHouse configuration
    CLICKHOUSE_DB=analytics
    CLICKHOUSE_USER=default
    CLICKHOUSE_PASSWORD=changeme

    # PostgreSQL configuration
    POSTGRES_DB=analytics
    POSTGRES_USER=changeme
    POSTGRES_PASSWORD=changeme

    # Redis configuration
    REDIS_PASSWORD=changeme

    # Ports in host:container format (Pangolin needs it like this)
    HOST_BACKEND_PORT=3001:3001
    HOST_CLIENT_PORT=3002:3002

    # Optional: Disable new user signups after creating admin account
    # DISABLE_SIGNUP=true

    # Optional: Mapbox token for globe visualizations
    # MAPBOX_TOKEN=your_mapbox_token
    ```

    <Callout type="info">
      The `HOST_BACKEND_PORT` and `HOST_CLIENT_PORT` values use the `host:container` format without binding to `127.0.0.1`. This is intentional — the Newt container inside the Docker network handles routing, so the ports do not need to be exposed to your host. Even if you already run services on ports 3001/3002 on your host, there will be no conflict.
    </Callout>
  </Step>

  <Step>
    ### Create Docker Compose File [#create-docker-compose-file]

    Create a `docker-compose.yml` file in the same directory. This includes a Newt container that connects Pangolin to your Rybbit services:

    ```yaml
    services:
      newt:
        image: fosrl/newt
        container_name: newt-rybbit
        restart: unless-stopped
        environment:
          - PANGOLIN_ENDPOINT=https://pangolin.yourdomain.com
          - NEWT_ID=your_newt_id
          - NEWT_SECRET=your_newt_secret

      clickhouse:
        container_name: clickhouse
        image: clickhouse/clickhouse-server:26.3.17.4
        volumes:
          - clickhouse-data:/var/lib/clickhouse
        configs:
          - source: clickhouse_network
            target: /etc/clickhouse-server/config.d/network.xml
          - source: clickhouse_logging
            target: /etc/clickhouse-server/config.d/logging_rules.xml
          # Profile (user-level) settings are only read from users.d, not config.d
          - source: clickhouse_user_settings
            target: /etc/clickhouse-server/users.d/user_settings.xml
        environment:
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        ports:
          - "8123:8123"

      postgres:
        image: postgres:17.4
        container_name: postgres
        environment:
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
        volumes:
          - postgres-data:/var/lib/postgresql/data
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        ports:
          - "5432:5432"

      redis:
        image: redis:8.6.4-alpine
        container_name: redis
        volumes:
          - redis-data:/data
        healthcheck:
          test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 5s
        restart: unless-stopped
        command:
          - redis-server
          - --requirepass
          - ${REDIS_PASSWORD:-changeme}
          - --appendonly
          - "yes"
          - --appendfsync
          - everysec
          - --maxmemory-policy
          - noeviction

      backend:
        image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}
        container_name: backend
        ports:
          - "${HOST_BACKEND_PORT:-127.0.0.1:3001:3001}"
        environment:
          - NODE_ENV=production
          - CLICKHOUSE_HOST=http://clickhouse:8123
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
          - POSTGRES_HOST=postgres
          - POSTGRES_PORT=5432
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - REDIS_HOST=redis
          - REDIS_PORT=6379
          - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
          - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
          - BASE_URL=${BASE_URL}
          - DISABLE_SIGNUP=${DISABLE_SIGNUP}
          - DISABLE_TELEMETRY=${DISABLE_TELEMETRY}
          - MAPBOX_TOKEN=${MAPBOX_TOKEN}
        depends_on:
          clickhouse:
            condition: service_healthy
          postgres:
            condition: service_started
          redis:
            condition: service_healthy
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3001/api/health"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped

      client:
        image: ghcr.io/rybbit-io/rybbit-client:${IMAGE_TAG:-latest}
        container_name: client
        ports:
          - "${HOST_CLIENT_PORT:-127.0.0.1:3002:3002}"
        environment:
          - NODE_ENV=production
          - NEXT_PUBLIC_BACKEND_URL=${BASE_URL}
          - NEXT_PUBLIC_DISABLE_SIGNUP=${DISABLE_SIGNUP}
        depends_on:
          - backend
        restart: unless-stopped

    volumes:
      clickhouse-data:
      postgres-data:
      redis-data:

    configs:
      clickhouse_network:
        content: |
          <clickhouse>
              <listen_host>0.0.0.0</listen_host>
          </clickhouse>

      clickhouse_logging:
        content: |
          <clickhouse>
            <logger>
                <level>warning</level>
                <console>true</console>
            </logger>
            <query_thread_log remove="remove"/>
            <query_log remove="remove"/>
            <text_log remove="remove"/>
            <trace_log remove="remove"/>
            <metric_log remove="remove"/>
            <asynchronous_metric_log remove="remove"/>
            <session_log remove="remove"/>
            <part_log remove="remove"/>
            <latency_log remove="remove"/>
            <processors_profile_log remove="remove"/>
          </clickhouse>

      clickhouse_user_settings:
        content: |
          <clickhouse>
            <profiles>
              <default>
                <enable_json_type>1</enable_json_type>
                <!-- 26.3+ enables async_insert by default; the backend already
                     batches app-side, so keep inserts synchronous -->
                <async_insert>0</async_insert>
                <log_queries>0</log_queries>
                <log_query_threads>0</log_query_threads>
                <log_processors_profiles>0</log_processors_profiles>
              </default>
            </profiles>
          </clickhouse>
    ```

    <Callout type="info">
      The `newt` service runs inside the same Docker network as your other containers. It connects to your Pangolin instance and routes traffic to `backend` and `client` by their container hostnames — no host port exposure needed for Pangolin to reach them.
    </Callout>
  </Step>

  <Step>
    ### Start Services [#start-services]

    Start all services:

    ```bash
    docker compose up -d
    ```

    Verify everything is running:

    ```bash
    docker compose ps
    ```

    Check that the backend is healthy:

    ```bash
    docker compose logs backend
    ```
  </Step>

  <Step>
    ### Configure Pangolin [#configure-pangolin]

    In your Pangolin dashboard, create a new site for your Rybbit domain and configure two resources:

    1. **Client resource** — routes the root domain to the Rybbit frontend:
       * Target: `client` (the Docker container hostname)
       * Port: `3002`

    2. **Backend resource** — routes `/api` traffic to the Rybbit backend:
       * Target: `backend` (the Docker container hostname)
       * Port: `3001`

    For both resources, add these custom headers in the Pangolin configuration:

    | Header              | Value                     |
    | ------------------- | ------------------------- |
    | `X-Forwarded-Proto` | `https`                   |
    | `X-Forwarded-Host`  | `tracking.yourdomain.com` |

        <img alt="Pangolin dashboard configuration" src="__img0" />

    <Callout type="warning">
      The `X-Forwarded-Proto` and `X-Forwarded-Host` headers are critical. Without them, API requests from the client to the backend will fail. This is the most common source of issues with this setup.
    </Callout>

    <Callout type="info">
      You do **not** need to enable "Advanced Mode" in Pangolin. The standard configuration with the correct headers is sufficient.
    </Callout>
  </Step>

  <Step>
    ### Access Rybbit [#access-rybbit]

    Navigate to `https://tracking.yourdomain.com` and create your admin account.

    If you see 404 errors on `/api` routes, double-check that:

    * Your `BETTER_AUTH_SECRET` is set and is at least 32 characters
    * The `X-Forwarded-Proto` and `X-Forwarded-Host` headers are configured in Pangolin
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

### Cannot create organizations or log in [#cannot-create-organizations-or-log-in]

This is almost always caused by a missing or invalid `BETTER_AUTH_SECRET`. Generate a proper secret:

```bash
openssl rand -hex 32
```

Add it to your `.env` file and restart the services:

```bash
docker compose down && docker compose up -d
```

### 404 errors on API routes [#404-errors-on-api-routes]

Verify that Pangolin is forwarding the correct headers. The `X-Forwarded-Proto` header must be `https` and `X-Forwarded-Host` must match your domain. Without these, the backend cannot properly handle requests.

### Backend health check failing [#backend-health-check-failing]

Check the backend logs for errors:

```bash
docker compose logs -f backend
```

Ensure ClickHouse and PostgreSQL are healthy:

```bash
docker compose ps
```

### Newt not connecting to Pangolin [#newt-not-connecting-to-pangolin]

Verify your Newt credentials and Pangolin endpoint:

```bash
docker compose logs -f newt-rybbit
```

Make sure `PANGOLIN_ENDPOINT`, `NEWT_ID`, and `NEWT_SECRET` are correct in your `docker-compose.yml`.

## Video Reference [#video-reference]

For a visual walkthrough of setting up Rybbit with Pangolin, see the official Pangolin YouTube guide:

<iframe width="560" height="315" src="https://www.youtube.com/embed/zk-ZhkNdyC8?start=5" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />


# Advanced self-hosting (/de/docs/self-hosting-guides/self-hosting-advanced)





This guide covers advanced configuration options for self-hosting Rybbit.

## Setup Script Options [#setup-script-options]

The setup script supports several options:

```bash
./setup.sh <domain_name> [options]
```

Available options:

* `--no-webserver`: Disable the built-in Caddy webserver
* `--backend-port <port>`: Set custom host port for backend (default: 3001)
* `--client-port <port>`: Set custom host port for client (default: 3002)
* `--mapbox-token <token>`: Set Mapbox API token (optional but recommended for globe visualizations)
* `--help`: Show help message

Examples:

```bash
# With Mapbox token
./setup.sh tracking.example.com --mapbox-token YOUR_MAPBOX_TOKEN

# Custom ports with built-in webserver
./setup.sh tracking.example.com --backend-port 8080 --client-port 8081

# Custom ports with your own webserver
./setup.sh tracking.example.com --no-webserver --backend-port 8080 --client-port 8081
```

<Callout type="info">
  When you specify custom ports, only the host port mapping changes. Inside the Docker containers, the services still use ports 3001 and 3002.
</Callout>

## Using Your Own Web Server [#using-your-own-web-server]

If you prefer to use your own web server instead of the built-in Caddy server, you can use the `--no-webserver` flag:

```bash
./setup.sh your.domain.name --no-webserver
```

This will:

* Not start the Caddy container
* Expose the backend service on host port 3001 (or your custom port)
* Expose the client service on host port 3002 (or your custom port)

<Callout type="info">
  For detailed configuration examples with Nginx, Traefik, NPM, and other reverse proxies, see our [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) guide.
</Callout>

## Environment Variables [#environment-variables]

The setup script creates a minimal `.env` file with only the essential variables:

```bash
DOMAIN_NAME=your.domain.com
BASE_URL=https://your.domain.com
BETTER_AUTH_SECRET=generated_secret
DISABLE_SIGNUP=false
```

Optional variables that can be added:

```bash
# Mapbox token for 3D map visualizations
MAPBOX_TOKEN=your_mapbox_token

# Database configuration (uses defaults if not specified)
CLICKHOUSE_PASSWORD=frog
POSTGRES_USER=frog
POSTGRES_PASSWORD=frog
POSTGRES_DB=analytics
CLICKHOUSE_DB=analytics

# Custom image tags
IMAGE_TAG=latest

# Port mapping (only needed for custom ports or --no-webserver)
HOST_BACKEND_PORT="3001:3001"
HOST_CLIENT_PORT="3002:3002"
```


# Manual Docker Compose setup (/de/docs/self-hosting-guides/self-hosting-manual)





This guide is for users who want to manually set up Rybbit using Docker Compose without the setup script. This is useful if you already have a reverse proxy setup (like Nginx, Traefik, or Coolify), or if you want more control over the configuration.

## Prerequisites [#prerequisites]

* Docker and Docker Compose installed
* A domain name pointed to your server
* Basic knowledge of Docker and environment variables

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Clone the Repository [#clone-the-repository]

    ```bash
    git clone https://github.com/rybbit-io/rybbit.git
    cd rybbit
    ```
  </Step>

  <Step>
    ### Create Environment File [#create-environment-file]

    Create a `.env` file in the root directory with the following content:

    ```bash
    # Required: Your domain and base URL
    DOMAIN_NAME=your.domain.com
    BASE_URL=https://your.domain.com

    # Required: Authentication secret (generate a random 32+ character string)
    BETTER_AUTH_SECRET=your-very-long-random-secret-string-here

    # Optional: Disable new user signups after creating admin account
    DISABLE_SIGNUP=false

    # Optional but recommended: Mapbox token for globe visualizations
    MAPBOX_TOKEN=your_mapbox_token

    # Optional: Custom ports (only needed if you want different ports)
    # HOST_BACKEND_PORT="3001:3001"
    # HOST_CLIENT_PORT="3002:3002"

    # Optional: Database credentials (defaults work fine)
    # CLICKHOUSE_PASSWORD=frog
    # POSTGRES_USER=frog
    # POSTGRES_PASSWORD=frog
    # POSTGRES_DB=analytics
    # CLICKHOUSE_DB=analytics
    ```

    <Callout type="info">
      To generate a secure `BETTER_AUTH_SECRET`, you can use:

      ```bash
      openssl rand -hex 32
      ```
    </Callout>
  </Step>

  <Step>
    ### Choose Your Setup Method [#choose-your-setup-method]

    <Tabs items="['Built-in Caddy (Automatic SSL)', 'Without Caddy']">
      <Tab value="Built-in Caddy (Automatic SSL)">
        If you don't have a reverse proxy and want automatic SSL certificates, use the default docker-compose.yml:

        ```bash
        docker compose up -d
        ```

        This will:

        * Start all services including Caddy
        * Automatically obtain SSL certificates
        * Make your app available at `https://your.domain.com`
      </Tab>

      <Tab value="Without Caddy">
        If you have your own reverse proxy (Nginx, Traefik, Coolify, etc.), you need to exclude Caddy and expose the ports:

        1. **Option B1: Modify the .env file**

           ```bash
           # Add these lines to expose ports
           HOST_BACKEND_PORT="3001:3001"
           HOST_CLIENT_PORT="3002:3002"
           ```

           Then start without Caddy:

           ```bash
           docker compose up -d backend client clickhouse postgres
           ```

        2. **Option B2: Use docker-compose.override.yml**
           Create a `docker-compose.override.yml` file:

           ```yaml
           services:
             backend:
               ports:
                 - "3001:3001"
             client:
               ports:
                 - "3002:3002"
           ```

           Then start without Caddy:

           ```bash
           docker compose up -d backend client clickhouse postgres
           ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure Your Reverse Proxy [#configure-your-reverse-proxy]

    If you're using your own reverse proxy, configure it to:

    * Proxy requests to `/api/*` to `http://localhost:3001`
    * Proxy all other requests to `http://localhost:3002`

    Example configurations:

    <Tabs items="['Nginx', 'Traefik']">
      <Tab value="Nginx">
        ```nginx
        server {
            listen 80;
            server_name your.domain.com;
            return 301 https://$host$request_uri;
        }

        server {
            listen 443 ssl;
            server_name your.domain.com;

            # Your SSL configuration here

            location /api/ {
                proxy_pass http://localhost:3001;
                proxy_set_header Host $host;
                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;
            }

            location / {
                proxy_pass http://localhost:3002;
                proxy_set_header Host $host;
                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;
            }
        }
        ```
      </Tab>

      <Tab value="Traefik">
        ```yml
        services:
          backend:
            labels:
              - "traefik.enable=true"
              - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && PathPrefix(`/api`)"
              - "traefik.http.routers.rybbit-api.tls.certresolver=letsencrypt"
              - "traefik.http.services.rybbit-api.loadbalancer.server.port=3001"
          
          client:
            labels:
              - "traefik.enable=true"
              - "traefik.http.routers.rybbit-client.rule=Host(`your.domain.com`)"
              - "traefik.http.routers.rybbit-client.tls.certresolver=letsencrypt"
              - "traefik.http.services.rybbit-client.loadbalancer.server.port=3002"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Start the Services [#start-the-services]

    ```bash
    # Start all services
    docker compose up -d

    # Or start specific services (without Caddy)
    docker compose up -d backend client clickhouse postgres
    ```
  </Step>

  <Step>
    ### Verify Setup [#verify-setup]

    Check that all services are running:

    ```bash
    docker compose ps
    ```

    Monitor logs:

    ```bash
    docker compose logs -f
    ```
  </Step>

  <Step>
    ### Create Admin Account [#create-admin-account]

    Navigate to `https://your.domain.com/signup` and create your admin account.
  </Step>
</Steps>

## Service Architecture [#service-architecture]

Rybbit consists of these services:

* **client**: Next.js frontend (port 3002)
* **backend**: Node.js API server (port 3001)
* **postgres**: User data and configuration
* **clickhouse**: Analytics data storage
* **redis**: Session tracking and background job queues
* **caddy**: Reverse proxy with automatic SSL (optional)

## Common Configurations [#common-configurations]

### Using Custom Ports [#using-custom-ports]

If you need different host ports (e.g., if 3001/3002 are already in use):

```bash
HOST_BACKEND_PORT="8080:3001"
HOST_CLIENT_PORT="8081:3002"
```

### Using with Coolify [#using-with-coolify]

Since Coolify uses Traefik instead of Caddy as proxy, some modifications have to be made in a `docker-compose.yaml` file to avoid conflicts. Specifically, you need to:

* remove Caddy service and volumes
* add network labels to all services
* remove `build` and `ports` properties from backend and client services

Here's a modified version of docker-compose that works on Coolify:

```yaml
services:
  clickhouse:
    container_name: clickhouse
    image: clickhouse/clickhouse-server:26.3.17.4
    volumes:
      - clickhouse-data:/var/lib/clickhouse
    configs:
      - source: clickhouse_network
        target: /etc/clickhouse-server/config.d/network.xml
      - source: clickhouse_logging
        target: /etc/clickhouse-server/config.d/logging_rules.xml
      # Profile (user-level) settings are only read from users.d, not config.d
      - source: clickhouse_user_settings
        target: /etc/clickhouse-server/users.d/user_settings.xml
    environment:
      - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
      - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
      - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://localhost:8123/ping",
        ]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    labels:
      - traefik.enable=false

  postgres:
    image: postgres:17.4
    container_name: postgres
    environment:
      - POSTGRES_USER=${POSTGRES_USER:-frog}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
      - POSTGRES_DB=${POSTGRES_DB:-analytics}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    labels:
      - traefik.enable=false

  redis:
    image: redis:8.6.4-alpine
    container_name: redis
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 5s
    restart: unless-stopped
    command:
      - redis-server
      - --requirepass
      - ${REDIS_PASSWORD:-changeme}
      - --appendonly
      - "yes"
      - --appendfsync
      - everysec
      - --maxmemory-policy
      - noeviction
    labels:
      - traefik.enable=false

  backend:
    image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}
    container_name: backend
    environment:
      - NODE_ENV=production
      - CLICKHOUSE_HOST=http://clickhouse:8123
      - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
      - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_DB=${POSTGRES_DB:-analytics}
      - POSTGRES_USER=${POSTGRES_USER:-frog}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
      - BASE_URL=${BASE_URL}
      - DOMAIN_NAME=${DOMAIN_NAME}
      - DISABLE_SIGNUP=${DISABLE_SIGNUP}
      - DISABLE_TELEMETRY=${DISABLE_TELEMETRY}
      - MAPBOX_TOKEN=${MAPBOX_TOKEN}
    depends_on:
      clickhouse:
        condition: service_healthy
      postgres:
        condition: service_started
      redis:
        condition: service_healthy
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://127.0.0.1:3001/api/health",
        ]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    labels:
      - traefik.enable=true
      - traefik.docker.network=coolify
      - traefik.http.routers.rybbit-backend.entrypoints=https
      - traefik.http.routers.rybbit-backend.tls=true
      - traefik.http.routers.rybbit-backend.rule=Host(`${DOMAIN_NAME}`) && (Path(`/api`) || PathPrefix(`/api/`))
      - traefik.http.services.rybbit-backend.loadbalancer.server.port=3001
      - traefik.http.routers.rybbit-backend.priority=100
      - traefik.http.middlewares.rybbit-forward-headers.headers.customrequestheaders.X-Forwarded-Proto=https
      - traefik.http.middlewares.rybbit-forward-headers.headers.customrequestheaders.X-Forwarded-Host=${DOMAIN_NAME}
      - traefik.http.routers.rybbit-backend.middlewares=rybbit-forward-headers

  client:
    image: ghcr.io/rybbit-io/rybbit-client:${IMAGE_TAG:-latest}
    container_name: client
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_BACKEND_URL=${BASE_URL}
      - NEXT_PUBLIC_DISABLE_SIGNUP=${DISABLE_SIGNUP}
      - DOMAIN_NAME=${DOMAIN_NAME}
    depends_on:
      - backend
    restart: unless-stopped
    labels:
      - traefik.enable=true
      - traefik.docker.network=coolify
      - traefik.http.routers.rybbit-client.entrypoints=https
      - traefik.http.routers.rybbit-client.tls=true
      - traefik.http.routers.rybbit-client.rule=Host(`${DOMAIN_NAME}`)
      - traefik.http.services.rybbit-client.loadbalancer.server.port=3002
      - traefik.http.routers.rybbit-client.priority=10

volumes:
  clickhouse-data:
  postgres-data:
  redis-data:

configs:
  clickhouse_network:
    content: |
      <clickhouse>
          <listen_host>0.0.0.0</listen_host>
      </clickhouse>

  clickhouse_logging:
    content: |
      <clickhouse>
        <logger>
            <level>warning</level>
            <console>true</console>
        </logger>
        <query_thread_log remove="remove"/>
        <query_log remove="remove"/>
        <text_log remove="remove"/>
        <trace_log remove="remove"/>
        <metric_log remove="remove"/>
        <asynchronous_metric_log remove="remove"/>
        <session_log remove="remove"/>
        <part_log remove="remove"/>
        <latency_log remove="remove"/>
        <processors_profile_log remove="remove"/>
      </clickhouse>

  clickhouse_user_settings:
    content: |
      <clickhouse>
        <profiles>
          <default>
            <enable_json_type>1</enable_json_type>
            <!-- 26.3+ enables async_insert by default; the backend already
                 batches app-side, so keep inserts synchronous -->
            <async_insert>0</async_insert>
            <log_queries>0</log_queries>
            <log_query_threads>0</log_query_threads>
            <log_processors_profiles>0</log_processors_profiles>
          </default>
        </profiles>
      </clickhouse>
```

To deploy Rybbit on Coolify, you need to:

1. Create a new project and resource using `docker-compose.yaml` file provided above
2. Make sure "Escape special characters in labels" option is unchecked when adding docker-compose file so that env variables in labels are read properly
3. Set the environment variables in Coolify's interface
4. Add a domain for `client` service in Coolify's interface
5. Deploy all services

Note: you don't need to add a domain for `backend` service in Coolify since client and backend services share the same domain.

### Using with Nginx Proxy Manager [#using-with-nginx-proxy-manager]

1. Set up port exposure in your .env:
   ```bash
   HOST_BACKEND_PORT="3001:3001"
   HOST_CLIENT_PORT="3002:3002"
   ```

2. Create a proxy host pointing to your server IP:3002

3. Add a custom location `/api/*` pointing to your server IP:3001

### Database Persistence [#database-persistence]

Data is automatically persisted in Docker volumes:

* `rybbit_clickhouse-data`: Analytics data
* `rybbit_postgres-data`: User accounts and site configurations

## Advanced Configurations [#advanced-configurations]

For specific reverse proxy setups, see our detailed guides:

* **[Custom Nginx Setup](/docs/self-hosting-guides/custom-nginx)** - Complete Nginx configuration with SSL
* **[Nginx Proxy Manager](/docs/self-hosting-guides/nginx-proxy-manager)** - NPM setup without port exposure

These guides provide step-by-step instructions for integrating Rybbit with your existing infrastructure.

## Troubleshooting [#troubleshooting]

### Services won't start [#services-wont-start]

```bash
# Check logs
docker compose logs

# Check service status
docker compose ps
```

### Port conflicts [#port-conflicts]

If you get port binding errors, either:

1. Change the host ports in your .env file
2. Stop the conflicting service
3. Use docker-compose.override.yml to customize ports

### Database connection issues [#database-connection-issues]

Ensure the database services are healthy:

```bash
docker compose ps
```

Both postgres and clickhouse should show "healthy" status.

<Callout type="info">
  For more advanced configurations and setup script options, see our [Advanced Self-Hosting Guide](/docs/self-hosting-guides/self-hosting-advanced).
</Callout>


# Create Annotation (/de/docs/api/annotations/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/annotations
    ```

    Creates an annotation. Any member with access to the site can create site annotations; organization-wide annotations (`scope: "organization"`) require an admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  title: { description: 'Short title (max 120 characters)', type: 'string', required: true },
  date: { description: 'ISO 8601 timestamp with Z or offset, or YYYY-MM-DD (read as midnight UTC)', type: 'string', required: true },
  endDate: { description: 'End of a range; must be after date', type: 'string', required: false },
  description: { description: 'Longer note (max 2000 characters)', type: 'string', required: false },
  color: { description: 'Marker color', type: 'string', typeDescription: '&#x22;amber&#x22; | &#x22;rose&#x22; | &#x22;sky&#x22; | &#x22;violet&#x22; | &#x22;lime&#x22;', required: false },
  icon: { description: 'A single emoji (or character) shown in the marker', type: 'string', required: false },
  isPublic: { description: 'Show on public dashboards and private links', type: 'boolean', default: 'false', required: false },
  scope: { description: 'Attach to this site or to every site in the organization', type: 'string', typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;', default: '&#x22;site&#x22;', required: false },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: { description: 'Always true', type: 'boolean' },
  annotationId: { description: 'ID of the new annotation', type: 'number' },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl -X POST "https://app.rybbit.io/api/sites/123/annotations" \
          -H "Authorization: Bearer YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "title": "Deployed v2.3.0",
            "date": "2026-08-24T14:10:00Z",
            "color": "sky",
            "scope": "organization"
          }'
        ```
      </Tab>

      <Tab value="Response">
        ```json
        { "success": true, "annotationId": 43 }
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Delete Annotation (/de/docs/api/annotations/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/annotations/:annotationId
    ```

    Deletes an annotation. Admins and owners can delete any annotation on their sites; members can delete only the annotations they created.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: { description: 'Site ID or site identifier', type: 'string | number', required: true },
  annotationId: { description: 'Annotation ID', type: 'number', required: true },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE "https://app.rybbit.io/api/sites/123/annotations/43" \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab value="Response">
        ```json
        { "success": true }
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Get Annotations (/de/docs/api/annotations/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/annotations
    ```

    Returns the annotations pinned to the site's traffic chart, ordered by date. Organization-wide annotations (those with a `null` `siteId`) are included for every site in the organization.

    Anonymous viewers of a public dashboard or a private link only receive annotations with `isPublic: true`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  start_date: {
    description: 'Only annotations that end on or after the start of this day (YYYY-MM-DD). May be sent without end_date.',
    type: 'string',
    required: false,
  },
  end_date: {
    description: 'Only annotations that start before the end of this day (YYYY-MM-DD). May be sent without start_date; must not precede start_date.',
    type: 'string',
    required: false,
  },
  time_zone: {
    description: 'IANA timezone the day bounds are read in',
    type: 'string',
    default: 'UTC',
    required: false,
  },
}"
    />

    ### Response [#response]

    An array of annotation objects.

    <TypeTable
      type="{
  annotationId: { description: 'Unique annotation ID', type: 'number' },
  siteId: { description: 'Site the annotation belongs to, or null for organization-wide annotations', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator user ID', type: 'string | null' },
  userName: { description: 'Creator display name', type: 'string | null' },
  title: { description: 'Short title shown on the chart', type: 'string' },
  description: { description: 'Longer note', type: 'string | null' },
  date: { description: 'ISO 8601 timestamp the annotation is pinned to', type: 'string' },
  endDate: { description: 'ISO 8601 end timestamp for range annotations', type: 'string | null' },
  color: { description: 'Marker color', type: 'string | null', typeDescription: '&#x22;amber&#x22; | &#x22;rose&#x22; | &#x22;sky&#x22; | &#x22;violet&#x22; | &#x22;lime&#x22; | null' },
  icon: { description: 'Single emoji shown in the marker', type: 'string | null' },
  isPublic: { description: 'Whether public dashboards and private links show it', type: 'boolean' },
  createdAt: { description: 'Creation timestamp', type: 'string' },
  updatedAt: { description: 'Last update timestamp', type: 'string' },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl "https://app.rybbit.io/api/sites/123/annotations?start_date=2026-08-01&end_date=2026-08-31" \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab value="Response">
        ```json
        [
          {
            "annotationId": 42,
            "siteId": 123,
            "organizationId": "org_abc",
            "userId": "user_xyz",
            "userName": "Bill",
            "title": "Product Hunt launch",
            "description": "Finished #2 Product of the Day.",
            "date": "2026-08-18T07:00:00.000Z",
            "endDate": null,
            "color": "amber",
            "icon": "🚀",
            "isPublic": true,
            "createdAt": "2026-08-18 07:05:12.1",
            "updatedAt": "2026-08-18 07:05:12.1"
          }
        ]
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Update Annotation (/de/docs/api/annotations/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:site/annotations/:annotationId
    ```

    Partial update: only the fields you send change. Admins and owners can edit any annotation on their sites; members can edit only the annotations they created. Changing `scope` requires an admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: { description: 'Site ID or site identifier', type: 'string | number', required: true },
  annotationId: { description: 'Annotation ID', type: 'number', required: true },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  title: { description: 'Short title (max 120 characters)', type: 'string', required: false },
  date: { description: 'ISO 8601 timestamp with Z or offset, or YYYY-MM-DD', type: 'string', required: false },
  endDate: { description: 'End of a range, or null to turn a range back into a point', type: 'string | null', required: false },
  description: { description: 'Longer note, or null to clear', type: 'string | null', required: false },
  color: { description: 'Marker color, or null for the neutral default', type: 'string | null', required: false },
  icon: { description: 'A single emoji (or character), or null to clear', type: 'string | null', required: false },
  isPublic: { description: 'Show on public dashboards and private links', type: 'boolean', required: false },
  scope: { description: 'Move between site and organization-wide', type: 'string', typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;', required: false },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl -X PUT "https://app.rybbit.io/api/sites/123/annotations/43" \
          -H "Authorization: Bearer YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{ "title": "Deployed v2.3.0 (rolled back)", "color": "rose" }'
        ```
      </Tab>

      <Tab value="Response">
        ```json
        { "success": true }
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Create Organization API Key (/de/docs/api/api-keys/create-org)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/api-keys
    ```

    Creates an API key **owned by the organization itself**, rather than by your user account. The key authenticates as the organization (org-admin authority over its sites), so it survives member departures, and its plan gating, [rate limits](/docs/api/getting-started#rate-limits-cloud-only), and key-count limit all follow the owning organization's subscription. Organization keys are issued with the `rb_org_` prefix.

    <Callout type="warn">
      You must be an 

      **owner or admin**

       of the target organization. This endpoint accepts your dashboard 

      **session**

       or an 

      **unrestricted (full-access) user API key**

       — scoped keys and organization keys are rejected, so an organization key cannot mint other keys.
    </Callout>

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'The ID of the organization that will own the key',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'A label for the key',
    type: 'string',
    required: true,
  },
  expiresIn: {
    description: 'Seconds until the key expires. Omit for a key that never expires.',
    type: 'number',
    required: false,
  },
  permissions: {
    description: 'Scope the key to specific `resource: action[]` pairs (e.g. `{ &#x22;analytics&#x22;: [&#x22;read&#x22;], &#x22;goals&#x22;: [&#x22;read&#x22;, &#x22;write&#x22;] }`). Omit entirely for a full-access key.',
    type: 'object',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created API key object. The full `key` value carries the `rb_org_` prefix.

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  key: {
    description: 'The secret key value (prefixed with `rb_org_`)',
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string',
  },
  start: {
    description: 'A non-secret prefix of the key for display',
    type: 'string',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string',
  },
  referenceId: {
    description: 'The ID of the organization that owns the key',
    type: 'string',
  },
  userId: {
    description: 'The ID of the admin/owner who created the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if the key never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
}"
    />

    **Note:** Additional fields may be present in the response object.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_123/api-keys" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"name": "CI pipeline", "expiresIn": 2592000}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations/org_123/api-keys',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'CI pipeline',
              expiresIn: 2592000
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/organizations/org_123/api-keys',
            json={
                'name': 'CI pipeline',
                'expiresIn': 2592000
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/org_123/api-keys");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'name' => 'CI pipeline',
            'expiresIn' => 2592000
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/organizations/org_123/api-keys")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          name: 'CI pipeline',
          expiresIn: 2592000
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "name": "CI pipeline",
          "expiresIn": 2592000
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/org_123/api-keys", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/organizations/org_123/api-keys")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "name": "CI pipeline",
                "expiresIn": 2592000
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/org_123/api-keys"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/organizations/org_123/api-keys", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    <Callout type="warn">
      The full 

      `key`

       value is returned 

      **only once**

      , at creation. Store it securely — it cannot be retrieved again.
    </Callout>

    ```json title="Response"
    {
      "id": "key_8f3a1b2c4d5e6f7g",
      "key": "rb_org_xxxxxxxxxxxxxxxxxxxx",
      "name": "CI pipeline",
      "start": "rb_org_xxxx",
      "prefix": "rb_org_",
      "referenceId": "org_123",
      "userId": "user_2a9b8c7d6e5f4g3h",
      "enabled": true,
      "expiresAt": "2026-07-25T12:00:00.000Z",
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-25T12:00:00.000Z",
      "rateLimitEnabled": false,
      "rateLimitMax": 10,
      "rateLimitTimeWindow": 86400000
    }
    ```

    <Callout>
      On Rybbit Cloud, organization API keys require the organization to be on a Standard or Pro plan; free/basic plans receive HTTP 403. Each organization also has a plan-based key-count limit — creating a key past the limit returns HTTP 403.
    </Callout>
  </div>
</div>


# Create API Key (/de/docs/api/api-keys/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/user/api-keys
    ```

    Creates a new API key scoped to your user account (and its organizations). To create a key owned by an organization instead, see [Create Organization API Key](/docs/api/api-keys/create-org).

    <Callout type="warn">
      This endpoint accepts your logged-in dashboard 

      **session**

       or an 

      **unrestricted (full-access) user API key**

      . Scoped keys and organization keys are rejected — so a scoped key cannot mint new keys, but a session or full-access key can. Send your session cookie or 

      `Authorization: Bearer`

       header with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'A label for the key',
    type: 'string',
    required: true,
  },
  expiresIn: {
    description: 'Seconds until the key expires. Omit for a key that never expires.',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created API key object.

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  key: {
    description: 'The secret key value',
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string',
  },
  start: {
    description: 'A non-secret prefix of the key for display',
    type: 'string',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string',
  },
  userId: {
    description: 'The ID of the user that owns the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if the key never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
}"
    />

    **Note:** Additional fields may be present in the response object.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/user/api-keys" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"name": "CI pipeline", "expiresIn": 2592000}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/user/api-keys',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'CI pipeline',
              expiresIn: 2592000
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/user/api-keys',
            json={
                'name': 'CI pipeline',
                'expiresIn': 2592000
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/user/api-keys");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'name' => 'CI pipeline',
            'expiresIn' => 2592000
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/user/api-keys")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          name: 'CI pipeline',
          expiresIn: 2592000
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "name": "CI pipeline",
          "expiresIn": 2592000
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/user/api-keys", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/user/api-keys")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "name": "CI pipeline",
                "expiresIn": 2592000
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/user/api-keys"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/user/api-keys", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    <Callout type="warn">
      The full 

      `key`

       value is returned 

      **only once**

      , at creation. Store it securely — it cannot be retrieved again.
    </Callout>

    ```json title="Response"
    {
      "id": "key_8f3a1b2c4d5e6f7g",
      "key": "rybbit_sk_live_xxxxxxxxxxxxxxxxxxxx",
      "name": "CI pipeline",
      "start": "rybbit_sk_live_xxxx",
      "prefix": "rybbit_sk_live_",
      "userId": "user_2a9b8c7d6e5f4g3h",
      "enabled": true,
      "expiresAt": "2026-07-25T12:00:00.000Z",
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-25T12:00:00.000Z",
      "rateLimitEnabled": false,
      "rateLimitMax": 10,
      "rateLimitTimeWindow": 86400000
    }
    ```

    <Callout>
      On Rybbit Cloud, API keys require a Standard or Pro plan; free/basic plans receive HTTP 403. 

      [Rate limits](/docs/api/getting-started#rate-limits-cloud-only)

       are charged to 

      **you**

      , the owning user, and are shared by every personal key you hold across every organization you belong to — creating a key does not add budget, and a plan change applies to keys you already have. For a budget that belongs to the organization instead, create an 

      [organization key](/docs/api/api-keys/create-org)

      .
    </Callout>
  </div>
</div>


# Delete API Key (/de/docs/api/api-keys/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/api-key/delete
    ```

    Revokes (deletes) an existing API key. The key is identified by its `keyId`.

    <Callout type="warn">
      This endpoint uses 

      **POST**

      , not HTTP DELETE. Revoking a key is immediate and permanent — any client still using it will start receiving 401 responses.
    </Callout>

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  keyId: {
    description: 'The id of the API key to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns a success flag.

    <TypeTable
      type="{
  success: {
    description: 'Indicates the API key was successfully deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/api-key/delete" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"keyId": "key_8f3a1b2c4d5e6f7g"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/api-key/delete',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              keyId: 'key_8f3a1b2c4d5e6f7g'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/api-key/delete',
            json={
                'keyId': 'key_8f3a1b2c4d5e6f7g'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/api-key/delete");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'keyId' => 'key_8f3a1b2c4d5e6f7g'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/api-key/delete")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          keyId: 'key_8f3a1b2c4d5e6f7g'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "keyId": "key_8f3a1b2c4d5e6f7g"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/api-key/delete", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/api-key/delete")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "keyId": "key_8f3a1b2c4d5e6f7g"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/api-key/delete"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/api-key/delete", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# List API Keys (/de/docs/api/api-keys/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/auth/api-key/list
    ```

    Returns all API keys owned by the authenticated user, or by a specific organization.

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID. If provided, returns organization-owned keys instead of your user-owned keys.',
    type: 'string',
    required: false,
  },
  limit: {
    description: 'Maximum number of keys to return.',
    type: 'number',
    required: false,
  },
  offset: {
    description: 'Number of keys to skip.',
    type: 'number',
    required: false,
  },
  sortBy: {
    description: 'Field to sort by (e.g. createdAt, name, expiresAt).',
    type: 'string',
    required: false,
  },
  sortDirection: {
    description: 'Sort direction.',
    type: &#x22;'asc' | 'desc'&#x22;,
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  apiKeys: {
    description: 'Array of API key objects.',
    type: 'ApiKey[]',
  },
  total: {
    description: 'Total number of matching keys.',
    type: 'number',
  },
  limit: {
    description: 'The limit that was applied.',
    type: 'number | null',
  },
  offset: {
    description: 'The offset that was applied.',
    type: 'number | null',
  },
}"
    />

    #### ApiKey Object [#apikey-object]

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string | null',
  },
  start: {
    description: 'Non-secret leading characters of the key, for display',
    type: 'string | null',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string | null',
  },
  userId: {
    description: 'ID of the user that owns the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if it never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
  requestCount: {
    description: 'Requests made in the current rate-limit window',
    type: 'number',
  },
  remaining: {
    description: 'Remaining requests, or null if not limited by count',
    type: 'number | null',
  },
  lastRequest: {
    description: 'Timestamp of the most recent request',
    type: 'string | null',
  },
  metadata: {
    description: 'Extra metadata stored on the key',
    type: 'object | null',
  },
  permissions: {
    description: 'Permissions associated with the key',
    type: 'object | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/auth/api-key/list?limit=20" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/api-key/list?limit=20',
          {
            method: 'GET',
            credentials: 'include'
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/auth/api-key/list?limit=20',
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/api-key/list?limit=20");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/api-key/list?limit=20")
        req = Net::HTTP::Get.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/auth/api-key/list?limit=20", nil)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/auth/api-key/list?limit=20")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/api-key/list?limit=20"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var response = await client.GetAsync("https://app.rybbit.io/api/auth/api-key/list?limit=20");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    <Callout>
      The secret key value is only returned once, at creation. This endpoint returns the non-secret 

      `start`

      /

      `prefix`

       for display, never the full key.
    </Callout>

    ```json title="Response"
    {
      "apiKeys": [
        {
          "id": "key_8f3a1b2c4d5e6f7g",
          "name": "CI pipeline",
          "start": "rybbit_sk_live_xxxx",
          "prefix": "rybbit_sk_live_",
          "userId": "user_2a9b8c7d6e5f4g3h",
          "enabled": true,
          "expiresAt": "2026-07-25T12:00:00.000Z",
          "createdAt": "2026-06-25T12:00:00.000Z",
          "updatedAt": "2026-06-25T12:00:00.000Z",
          "rateLimitEnabled": false,
          "rateLimitMax": 10,
          "rateLimitTimeWindow": 86400000,
          "requestCount": 42,
          "remaining": null,
          "lastRequest": "2026-06-25T13:30:00.000Z",
          "metadata": null,
          "permissions": null
        }
      ],
      "total": 1,
      "limit": 20,
      "offset": 0
    }
    ```
  </div>
</div>


# Update API Key (/de/docs/api/api-keys/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/api-key/update
    ```

    <Callout>
      This endpoint uses 

      **POST**

      , not PUT or PATCH.
    </Callout>

    Updates mutable fields on an existing API key. The key is identified by its `keyId`.

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  keyId: {
    description: 'The id of the API key to update',
    type: 'string',
    required: true,
  },
  name: {
    description: 'A new label for the key',
    type: 'string',
    required: false,
  },
  enabled: {
    description: 'Enable or disable the key',
    type: 'boolean',
    required: false,
  },
  expiresIn: {
    description: 'New expiry in seconds from now. Pass null to make the key never expire.',
    type: 'number | null',
    required: false,
  },
  rateLimitEnabled: {
    description: 'Legacy per-key rate limit toggle. Has no effect — [rate limits](/docs/api/getting-started#rate-limits-cloud-only) are enforced per credential owner and follow that owner\'s plan',
    type: 'boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the updated API key object (without the secret key value).

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string | null',
  },
  start: {
    description: 'Non-secret leading characters of the key, for display',
    type: 'string | null',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string | null',
  },
  userId: {
    description: 'ID of the user that owns the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if it never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
}"
    />

    **Note:** Additional fields may be present in the response object.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/api-key/update" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"keyId": "key_8f3a1b2c4d5e6f7g", "name": "CI pipeline (rotated)", "enabled": true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/api-key/update',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              keyId: 'key_8f3a1b2c4d5e6f7g',
              name: 'CI pipeline (rotated)',
              enabled: true
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/api-key/update',
            json={
                'keyId': 'key_8f3a1b2c4d5e6f7g',
                'name': 'CI pipeline (rotated)',
                'enabled': True
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/api-key/update");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'keyId' => 'key_8f3a1b2c4d5e6f7g',
            'name' => 'CI pipeline (rotated)',
            'enabled' => true
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/api-key/update")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          keyId: 'key_8f3a1b2c4d5e6f7g',
          name: 'CI pipeline (rotated)',
          enabled: true
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "keyId": "key_8f3a1b2c4d5e6f7g",
          "name": "CI pipeline (rotated)",
          "enabled": true
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/api-key/update", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/api-key/update")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "keyId": "key_8f3a1b2c4d5e6f7g",
                "name": "CI pipeline (rotated)",
                "enabled": true
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\", \"name\": \"CI pipeline (rotated)\", \"enabled\": true}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/api-key/update"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\", \"name\": \"CI pipeline (rotated)\", \"enabled\": true}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/api-key/update", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "key_8f3a1b2c4d5e6f7g",
      "name": "CI pipeline (rotated)",
      "start": "rybbit_sk_live_xxxx",
      "prefix": "rybbit_sk_live_",
      "userId": "user_2a9b8c7d6e5f4g3h",
      "enabled": true,
      "expiresAt": "2026-07-25T12:00:00.000Z",
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-26T12:00:00.000Z",
      "rateLimitEnabled": false,
      "rateLimitMax": 10,
      "rateLimitTimeWindow": 86400000
    }
    ```
  </div>
</div>


# Get AI Summary (/de/docs/api/bots/ai-summary)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/ai-summary
    ```

    Returns one row per AI operator: how much of your site it read, and how many visits it sent back.

    The two numbers come from different places. Reads are bot events whose user agent names the operator; visits back are sessions in your normal analytics that arrived from that company's product (the `AI` acquisition channel). Neither is very interesting alone — "OpenAI read 4,120 pages and sent 12 visits" is the sentence this endpoint exists to produce.

    Operators that only read, and operators that only referred, both appear; the missing side reads `0`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Filters apply to both halves, using the bot filter subset described in [Get Bots by Dimension](/docs/api/bots/by-dimension).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of operator rows, ordered by reads descending',
    type: 'AiSummaryRow[]',
  },
}"
    />

    #### AiSummaryRow Object [#aisummaryrow-object]

    <TypeTable
      type="{
  operator: {
    description: 'Who runs the bot, e.g. &#x22;OpenAI&#x22;',
    type: 'string',
  },
  crawls: {
    description: 'Total AI requests from this operator',
    type: 'number',
  },
  training_crawls: {
    description: 'Requests with purpose ai_training',
    type: 'number',
  },
  search_crawls: {
    description: 'Requests with purpose ai_search',
    type: 'number',
  },
  agent_requests: {
    description: 'Requests with purpose ai_agent',
    type: 'number',
  },
  referrals: {
    description: 'Sessions that arrived from this operator\'s product',
    type: 'number',
  },
  crawls_per_referral: {
    description: 'Reads per visit sent back. 0 when the operator sent nobody back — there is no rate to report.',
    type: 'number',
  },
}"
    />

    <Callout>
      Only bots that execute JavaScript reach Rybbit. Crawlers that fetch HTML and run nothing — which includes most training crawlers — are absent unless your server reports them. See [Bot detection](/docs/bot-detection#reporting-crawlers-that-never-run-javascript).
    </Callout>
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/ai-summary?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/ai-summary?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/ai-summary',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York',
            },
            headers={'Authorization': 'Bearer your_api_key_here'},
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "operator": "OpenAI",
          "crawls": 6120,
          "training_crawls": 4400,
          "search_crawls": 900,
          "agent_requests": 820,
          "referrals": 214,
          "crawls_per_referral": 28.6
        },
        {
          "operator": "Perplexity",
          "crawls": 1904,
          "training_crawls": 0,
          "search_crawls": 1300,
          "agent_requests": 604,
          "referrals": 341,
          "crawls_per_referral": 5.6
        }
      ]
    }
    ```
  </div>
</div>


# Get Bots by Dimension (/de/docs/api/bots/by-dimension)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/by-dimension
    ```

    Returns bot requests broken down by a dimension.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Bot filtering supports a subset of filter parameters: `browser`, `browser_version`, `operating_system`, `operating_system_version`, `country`, `region`, `city`, `device_type`, `referrer`, `hostname`, `pathname`, `querystring`, `dimensions`, `user_id`, `lat`, and `lon`.

    <TypeTable
      type="{
  dimension: {
    description: 'The dimension to group by',
    type: 'string',
    typeDescription: '&#x22;browser&#x22; | &#x22;browser_version&#x22; | &#x22;operating_system&#x22; | &#x22;operating_system_version&#x22; | &#x22;country&#x22; | &#x22;region&#x22; | &#x22;city&#x22; | &#x22;device_type&#x22; | &#x22;referrer&#x22; | &#x22;hostname&#x22; | &#x22;pathname&#x22; | &#x22;dimensions&#x22; | &#x22;asn_org&#x22; | &#x22;asn_provider&#x22; | &#x22;bot_category&#x22; | &#x22;bot_name&#x22; | &#x22;bot_operator&#x22; | &#x22;bot_purpose&#x22; | &#x22;matched_ua_pattern&#x22;',
    required: true,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  purpose: {
    description: 'Restrict results to one bot purpose. &#x22;ai&#x22; covers all three AI purposes; &#x22;ai_crawler&#x22; covers training and answer-engine crawling but not agents.',
    type: 'string',
    typeDescription: '&#x22;ai&#x22; | &#x22;ai_crawler&#x22; | &#x22;ai_training&#x22; | &#x22;ai_search&#x22; | &#x22;ai_agent&#x22; | &#x22;search&#x22; | &#x22;social_preview&#x22; | &#x22;seo&#x22; | &#x22;monitoring&#x22; | &#x22;security&#x22; | &#x22;scripted&#x22; | &#x22;headless&#x22;',
    required: false,
  },
  layer: {
    description: 'Restrict results to a single detection layer',
    type: 'string',
    typeDescription: '&#x22;ua_pattern&#x22; | &#x22;header_heuristics&#x22; | &#x22;client_signals&#x22; | &#x22;bot_asn&#x22; | &#x22;rate_anomaly&#x22;',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Paginated response object',
    type: 'PaginatedResponse',
  },
}"
    />

    #### PaginatedResponse Object [#paginatedresponse-object]

    <TypeTable
      type="{
  data: {
    description: 'Array of dimension breakdown objects',
    type: 'BotDimension[]',
  },
  totalCount: {
    description: 'Total number of distinct dimension values',
    type: 'number',
  },
}"
    />

    #### BotDimension Object [#botdimension-object]

    <TypeTable
      type="{
  value: {
    description: 'The dimension value',
    type: 'string',
  },
  hostname: {
    description: 'Hostname (only populated when dimension is &#x22;pathname&#x22;, otherwise empty)',
    type: 'string',
  },
  count: {
    description: 'Number of bot requests for this value',
    type: 'number',
  },
  percentage: {
    description: 'Share of bot requests for this value',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/by-dimension',
            params={
                'dimension': 'browser',
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "data": [
          { "value": "Chrome", "hostname": "", "count": 980, "percentage": 53.26 },
          { "value": "HeadlessChrome", "hostname": "", "count": 540, "percentage": 29.35 }
        ],
        "totalCount": 12
      }
    }
    ```
  </div>
</div>


# Get Bot Overview (/de/docs/api/bots/overview)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/overview
    ```

    Returns aggregate bot-traffic metrics with a breakdown by detection layer.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Bot filtering supports a subset of filter parameters: `browser`, `browser_version`, `operating_system`, `operating_system_version`, `country`, `region`, `city`, `device_type`, `referrer`, `hostname`, `pathname`, `querystring`, `dimensions`, `user_id`, `lat`, and `lon`.

    <TypeTable
      type="{
  layer: {
    description: 'Restrict results to a single detection layer',
    type: 'string',
    typeDescription: '&#x22;ua_pattern&#x22; | &#x22;header_heuristics&#x22; | &#x22;client_signals&#x22; | &#x22;bot_asn&#x22; | &#x22;rate_anomaly&#x22;',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  bot_requests: {
    description: 'Total bot requests',
    type: 'number',
  },
  total_events: {
    description: 'Total requests (bots + humans)',
    type: 'number',
  },
  bot_percentage: {
    description: 'Bot requests as a percentage of all requests',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  ai_requests: {
    description: 'Requests from named AI systems: training crawlers, answer-engine indexers, and user-triggered agents',
    type: 'number',
  },
  ai_agent_requests: {
    description: 'Requests from user-triggered AI agents (a person asked an assistant to open the page)',
    type: 'number',
  },
  ai_crawler_requests: {
    description: 'Requests from AI training crawlers and answer-engine indexers',
    type: 'number',
  },
  ua_pattern: {
    description: 'Bot requests flagged by the user-agent pattern layer',
    type: 'number',
  },
  header_heuristics: {
    description: 'Bot requests flagged by the header-heuristics layer',
    type: 'number',
  },
  client_signals: {
    description: 'Bot requests flagged by the client-signals layer',
    type: 'number',
  },
  bot_asn: {
    description: 'Bot requests flagged by the known-bot-ASN layer',
    type: 'number',
  },
  rate_anomaly: {
    description: 'Bot requests flagged by the rate-anomaly layer',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/overview',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "bot_requests": 1840,
        "total_events": 48933,
        "bot_percentage": 3.76,
        "ai_requests": 940,
        "ai_agent_requests": 180,
        "ai_crawler_requests": 760,
        "ua_pattern": 1200,
        "header_heuristics": 410,
        "client_signals": 95,
        "bot_asn": 120,
        "rate_anomaly": 15
      }
    }
    ```
  </div>
</div>


# Get Bot Time Series (/de/docs/api/bots/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/time-series
    ```

    Returns bot request counts over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Bot filtering supports a subset of filter parameters: `browser`, `browser_version`, `operating_system`, `operating_system_version`, `country`, `region`, `city`, `device_type`, `referrer`, `hostname`, `pathname`, `querystring`, `dimensions`, `user_id`, `lat`, and `lon`.

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket granularity',
    type: 'string',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
  },
  purpose: {
    description: 'Restrict results to one bot purpose. &#x22;ai&#x22; covers all three AI purposes; &#x22;ai_crawler&#x22; covers training and answer-engine crawling but not agents.',
    type: 'string',
    typeDescription: '&#x22;ai&#x22; | &#x22;ai_crawler&#x22; | &#x22;ai_training&#x22; | &#x22;ai_search&#x22; | &#x22;ai_agent&#x22; | &#x22;search&#x22; | &#x22;social_preview&#x22; | &#x22;seo&#x22; | &#x22;monitoring&#x22; | &#x22;security&#x22; | &#x22;scripted&#x22; | &#x22;headless&#x22;',
    required: false,
  },
  layer: {
    description: 'Restrict results to a single detection layer',
    type: 'string',
    typeDescription: '&#x22;ua_pattern&#x22; | &#x22;header_heuristics&#x22; | &#x22;client_signals&#x22; | &#x22;bot_asn&#x22; | &#x22;rate_anomaly&#x22;',
    required: false,
  },
}"
    />

    #### Bucket Selection Guide [#bucket-selection-guide]

    | Bucket         | Best For                             |
    | -------------- | ------------------------------------ |
    | `minute`       | Real-time monitoring (last hour)     |
    | `five_minutes` | Short-term analysis (last few hours) |
    | `hour`         | Daily analysis                       |
    | `day`          | Weekly/monthly analysis              |
    | `week`         | Monthly/quarterly analysis           |
    | `month`        | Yearly analysis                      |

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
  },
  bot_requests: {
    description: 'Number of bot requests in this bucket',
    type: 'number',
  },
  ai_agent_requests: {
    description: 'Requests in this bucket from user-triggered AI agents',
    type: 'number',
  },
  ai_crawler_requests: {
    description: 'Requests in this bucket from AI training crawlers and answer-engine indexers',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/time-series',
            params={
                'bucket': 'hour',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        { "time": "2024-01-15 13:00:00", "bot_requests": 42 },
        { "time": "2024-01-15 14:00:00", "bot_requests": 58 }
      ]
    }
    ```
  </div>
</div>


# Get Error Events (/de/docs/api/errors/events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/errors/events
    ```

    Returns individual error occurrences for a specific error message, with full context including stack traces.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  errorMessage: {
    description: 'The error message to filter by',
    type: 'string',
    required: true,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    required: false,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 20,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of error event objects',
    type: 'ErrorEvent[]',
  },
}"
    />

    #### ErrorEvent Object [#errorevent-object]

    <TypeTable
      type="{
  timestamp: {
    description: 'When the error occurred',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  session_id: {
    description: 'Session identifier',
    type: 'string',
  },
  user_id: {
    description: 'User identifier',
    type: 'string | null',
  },
  pathname: {
    description: 'Page where error occurred',
    type: 'string',
  },
  hostname: {
    description: 'Hostname',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  message: {
    description: 'Error message',
    type: 'string',
  },
  stack: {
    description: 'Stack trace',
    type: 'string | null',
  },
  fileName: {
    description: 'Source file name',
    type: 'string | null',
  },
  lineNumber: {
    description: 'Line number in source',
    type: 'number | null',
  },
  columnNumber: {
    description: 'Column number in source',
    type: 'number | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          `https://app.rybbit.io/api/sites/1/errors/events?errorMessage=${encodeURIComponent("Cannot read property 'map' of undefined")}&limit=10`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/errors/events',
            params={
                'errorMessage': "Cannot read property 'map' of undefined",
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "timestamp": "2024-01-31T14:22:00.000Z",
          "session_id": "sess_abc123",
          "user_id": "user_xyz789",
          "pathname": "/dashboard",
          "hostname": "app.example.com",
          "browser": "Chrome",
          "browser_version": "120.0.0",
          "operating_system": "macOS",
          "device_type": "desktop",
          "country": "US",
          "message": "Cannot read property 'map' of undefined",
          "stack": "TypeError: Cannot read property 'map' of undefined\n    at Dashboard (dashboard.js:42:15)\n    at renderWithHooks (react-dom.js:1234:22)",
          "fileName": "dashboard.js",
          "lineNumber": 42,
          "columnNumber": 15
        }
      ]
    }
    ```
  </div>
</div>


# Get Error Names (/de/docs/api/errors/names)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/errors/names
    ```

    Returns a list of unique error messages with occurrence counts and affected session counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed). Enables paginated response format.',
    type: 'number',
    required: false,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 10,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of error objects (or paginated wrapper)',
    type: 'Error[] | PaginatedResponse',
  },
}"
    />

    #### Error Object [#error-object]

    <TypeTable
      type="{
  value: {
    description: 'Error message',
    type: 'string',
  },
  errorName: {
    description: 'Error type (TypeError, ReferenceError, etc.)',
    type: 'string',
  },
  count: {
    description: 'Total occurrences',
    type: 'number',
  },
  sessionCount: {
    description: 'Unique sessions affected',
    type: 'number',
  },
  percentage: {
    description: 'Percentage of total error sessions',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/errors/names',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "value": "Cannot read property 'map' of undefined",
          "errorName": "TypeError",
          "count": 156,
          "sessionCount": 89,
          "percentage": 34.5
        },
        {
          "value": "NetworkError when attempting to fetch resource",
          "errorName": "TypeError",
          "count": 98,
          "sessionCount": 72,
          "percentage": 27.9
        },
        {
          "value": "foo is not defined",
          "errorName": "ReferenceError",
          "count": 45,
          "sessionCount": 38,
          "percentage": 14.7
        }
      ]
    }
    ```
  </div>
</div>


# Get Error Time Series (/de/docs/api/errors/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/errors/time-series
    ```

    Returns error occurrence counts over time for a specific error message. Useful for tracking error trends and identifying when issues started.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  errorMessage: {
    description: 'The error message to filter by',
    type: 'string',
    required: true,
  },
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request succeeded',
    type: 'boolean',
  },
  data: {
    description: 'Array of time-bucketed counts',
    type: 'ErrorBucket[]',
  },
}"
    />

    #### ErrorBucket Object [#errorbucket-object]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  error_count: {
    description: 'Number of errors in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          `https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=${encodeURIComponent("Cannot read property 'map' of undefined")}&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/errors/time-series',
            params={
                'errorMessage': "Cannot read property 'map' of undefined",
                'bucket': 'hour',
                'start_date': '2024-01-30',
                'end_date': '2024-01-31',
                'time_zone': 'UTC'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": [
        {
          "time": "2024-01-30T00:00:00.000Z",
          "error_count": 5
        },
        {
          "time": "2024-01-30T01:00:00.000Z",
          "error_count": 3
        },
        {
          "time": "2024-01-30T02:00:00.000Z",
          "error_count": 8
        },
        {
          "time": "2024-01-30T03:00:00.000Z",
          "error_count": 2
        }
      ]
    }
    ```
  </div>
</div>


# Get Event Counts (/de/docs/api/events/count)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/count
    ```

    Returns time-bucketed event counts grouped by event type.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'day',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
  },
  pageview_count: {
    description: 'Number of pageviews in this bucket',
    type: 'number',
  },
  custom_event_count: {
    description: 'Number of custom events in this bucket',
    type: 'number',
  },
  performance_count: {
    description: 'Number of performance events in this bucket',
    type: 'number',
  },
  outbound_count: {
    description: 'Number of outbound link events in this bucket',
    type: 'number',
  },
  error_count: {
    description: 'Number of error events in this bucket',
    type: 'number',
  },
  button_click_count: {
    description: 'Number of button click events in this bucket',
    type: 'number',
  },
  copy_count: {
    description: 'Number of copy events in this bucket',
    type: 'number',
  },
  form_submit_count: {
    description: 'Number of form submit events in this bucket',
    type: 'number',
  },
  input_change_count: {
    description: 'Number of input change events in this bucket',
    type: 'number',
  },
  event_count: {
    description: 'Total events across all types in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/events/count',
            params={
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-15 00:00:00",
          "pageview_count": 4820,
          "custom_event_count": 312,
          "performance_count": 1200,
          "outbound_count": 88,
          "error_count": 14,
          "button_click_count": 540,
          "copy_count": 9,
          "form_submit_count": 33,
          "input_change_count": 120,
          "event_count": 7136
        }
      ]
    }
    ```
  </div>
</div>


# Get Events (/de/docs/api/events/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events
    ```

    Returns a paginated list of events (pageviews, custom events, and outbound clicks).

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page_size: {
    description: 'Number of results per page',
    type: 'number',
    default: 50,
  },
  since_timestamp: {
    description: 'Poll for new events after this timestamp (ISO 8601). Used for realtime polling. Returns up to 500 events.',
    type: 'string',
  },
  before_timestamp: {
    description: 'Fetch events before this timestamp (ISO 8601). Used for cursor-based pagination (scrolling back).',
    type: 'string',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of event objects',
    type: 'Event[]',
  },
  cursor: {
    description: 'Cursor metadata for pagination (only present when not using since_timestamp)',
    type: '{ hasMore: boolean, oldestTimestamp: string | null }',
  },
}"
    />

    #### Event Object [#event-object]

    <TypeTable
      type="{
  timestamp: {
    description: 'Event timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;copy&#x22; | &#x22;form_submit&#x22; | &#x22;input_change&#x22;',
  },
  event_name: {
    description: 'Custom event name',
    type: 'string',
  },
  properties: {
    description: 'Event properties as JSON string',
    type: 'string',
  },
  session_id: {
    description: 'Session identifier',
    type: 'string',
  },
  user_id: {
    description: 'User identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Identified user ID (if user has been identified)',
    type: 'string',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
  },
  querystring: {
    description: 'URL query string',
    type: 'string',
  },
  hostname: {
    description: 'Hostname',
    type: 'string',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  language: {
    description: 'Browser language',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  lat: {
    description: 'Latitude',
    type: 'number',
  },
  lon: {
    description: 'Longitude',
    type: 'number',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events',
            params={
                'page_size': 50,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "timestamp": "2024-01-31T14:22:00.000Z",
          "type": "custom_event",
          "event_name": "signup",
          "properties": "{\"plan\":\"pro\",\"source\":\"homepage\"}",
          "session_id": "abc123def456",
          "user_id": "user_abc123",
          "identified_user_id": "",
          "pathname": "/signup",
          "querystring": "",
          "hostname": "example.com",
          "page_title": "Sign Up",
          "referrer": "https://google.com",
          "browser": "Chrome",
          "browser_version": "120.0",
          "operating_system": "macOS",
          "operating_system_version": "14.0",
          "language": "en-US",
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "lat": 37.7749,
          "lon": -122.4194,
          "screen_width": 1920,
          "screen_height": 1080,
          "device_type": "desktop"
        },
        {
          "timestamp": "2024-01-31T14:21:00.000Z",
          "type": "pageview",
          "event_name": "",
          "properties": "{}",
          "session_id": "abc123def456",
          "user_id": "user_abc123",
          "identified_user_id": "",
          "pathname": "/pricing",
          "querystring": "",
          "hostname": "example.com",
          "page_title": "Pricing",
          "referrer": "https://example.com/",
          "browser": "Chrome",
          "browser_version": "120.0",
          "operating_system": "macOS",
          "operating_system_version": "14.0",
          "language": "en-US",
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "lat": 37.7749,
          "lon": -122.4194,
          "screen_width": 1920,
          "screen_height": 1080,
          "device_type": "desktop"
        }
      ],
      "cursor": {
        "hasMore": true,
        "oldestTimestamp": "2024-01-31T14:21:00.000Z"
      }
    }
    ```
  </div>
</div>


# Get Event Names (/de/docs/api/events/names)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/names
    ```

    Returns a list of unique custom event names with their occurrence counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of event name objects',
    type: 'EventName[]',
  },
}"
    />

    #### EventName Object [#eventname-object]

    <TypeTable
      type="{
  eventName: {
    description: 'Name of the custom event',
    type: 'string',
  },
  count: {
    description: 'Number of occurrences',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events/names',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "eventName": "signup",
          "count": 1250
        },
        {
          "eventName": "purchase",
          "count": 320
        },
        {
          "eventName": "add_to_cart",
          "count": 890
        },
        {
          "eventName": "newsletter_subscribe",
          "count": 456
        }
      ]
    }
    ```
  </div>
</div>


# Get Outbound Links (/de/docs/api/events/outbound)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/outbound
    ```

    Returns a list of outbound link clicks with their occurrence counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of outbound link objects',
    type: 'OutboundLink[]',
  },
}"
    />

    #### OutboundLink Object [#outboundlink-object]

    <TypeTable
      type="{
  url: {
    description: 'The outbound URL that was clicked',
    type: 'string',
  },
  count: {
    description: 'Number of clicks',
    type: 'number',
  },
  lastClicked: {
    description: 'Most recent click timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events/outbound',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "url": "https://github.com/example/repo",
          "count": 245,
          "lastClicked": "2024-01-31T14:22:00.000Z"
        },
        {
          "url": "https://twitter.com/example",
          "count": 189,
          "lastClicked": "2024-01-31T12:15:00.000Z"
        },
        {
          "url": "https://docs.example.com",
          "count": 156,
          "lastClicked": "2024-01-31T10:30:00.000Z"
        }
      ]
    }
    ```
  </div>
</div>


# Get Event Properties (/de/docs/api/events/properties)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/properties
    ```

    Returns property key-value pairs for a specific event name with their occurrence counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  event_name: {
    description: 'Event name to get properties for',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of property objects',
    type: 'EventProperty[]',
  },
}"
    />

    #### EventProperty Object [#eventproperty-object]

    <TypeTable
      type="{
  propertyKey: {
    description: 'Property key name',
    type: 'string',
  },
  propertyValue: {
    description: 'Property value',
    type: 'string',
  },
  count: {
    description: 'Number of occurrences',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events/properties',
            params={
                'event_name': 'signup',
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "propertyKey": "plan",
          "propertyValue": "pro",
          "count": 520
        },
        {
          "propertyKey": "plan",
          "propertyValue": "starter",
          "count": 430
        },
        {
          "propertyKey": "plan",
          "propertyValue": "enterprise",
          "count": 300
        },
        {
          "propertyKey": "source",
          "propertyValue": "homepage",
          "count": 650
        },
        {
          "propertyKey": "source",
          "propertyValue": "pricing",
          "count": 600
        }
      ]
    }
    ```
  </div>
</div>


# Get Event Time Series (/de/docs/api/events/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/time-series
    ```

    Returns time-bucketed counts for the top custom events.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
  },
  limit: {
    description: 'Number of top custom events (by total count) to include',
    type: 'number',
    typeDescription: 'Range: 1-10',
    default: 5,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
  },
  event_name: {
    description: 'Name of the custom event',
    type: 'string',
  },
  event_count: {
    description: 'Number of times the event occurred in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/events/time-series',
            params={
                'bucket': 'hour',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York',
                'limit': 5
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        { "time": "2024-01-15 13:00:00", "event_name": "signup", "event_count": 42 },
        { "time": "2024-01-15 13:00:00", "event_name": "purchase", "event_count": 12 }
      ]
    }
    ```
  </div>
</div>


# Analyze Funnel (/de/docs/api/funnels/analyze)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/funnels/analyze
    ```

    Analyzes a funnel and returns step-by-step conversion data. Sessions must complete steps in order (step 2 must occur after step 1, etc.).

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Request Body [#request-body]

    <TypeTable
      type="{
  steps: {
    description: 'Array of funnel steps (minimum 2)',
    type: 'FunnelStep[]',
    required: true,
  },
}"
    />

    #### FunnelStep Object [#funnelstep-object]

    <TypeTable
      type="{
  type: {
    description: 'Step type',
    type: 'string',
    typeDescription: '&#x22;page&#x22; | &#x22;event&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;form_submit&#x22; | &#x22;copy&#x22;',
    required: true,
  },
  value: {
    description: 'Page path pattern or event name',
    type: 'string',
    required: true,
  },
  name: {
    description: 'Display name for the step',
    type: 'string',
    required: false,
  },
  hostname: {
    description: 'Filter by specific hostname',
    type: 'string',
    required: false,
  },
  eventPropertyKey: {
    description: 'Event property key to match (for event steps)',
    type: 'string',
    required: false,
  },
  eventPropertyValue: {
    description: 'Event property value to match',
    type: 'string | number | boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of step results',
    type: 'FunnelStepResult[]',
  },
}"
    />

    #### FunnelStepResult Object [#funnelstepresult-object]

    <TypeTable
      type="{
  step_number: {
    description: 'Step number (1-indexed)',
    type: 'number',
  },
  step_name: {
    description: 'Step name',
    type: 'string',
  },
  sessions: {
    description: 'Number of sessions that reached this step',
    type: 'number',
  },
  visitors: {
    description: 'Deprecated alias of `sessions`, kept for backwards compatibility',
    type: 'number',
  },
  conversion_rate: {
    description: 'Percentage of step 1 sessions that reached this step',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  dropoff_rate: {
    description: 'Percentage who dropped off from the previous step',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "steps": [
              { "type": "page", "value": "/", "name": "Homepage" },
              { "type": "page", "value": "/pricing", "name": "Pricing" },
              { "type": "page", "value": "/signup", "name": "Signup" },
              { "type": "event", "value": "signup_complete", "name": "Complete" }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              steps: [
                { type: 'page', value: '/', name: 'Homepage' },
                { type: 'page', value: '/pricing', name: 'Pricing' },
                { type: 'page', value: '/signup', name: 'Signup' },
                { type: 'event', value: 'signup_complete', name: 'Complete' }
              ]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/funnels/analyze',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            json={
                'steps': [
                    { 'type': 'page', 'value': '/', 'name': 'Homepage' },
                    { 'type': 'page', 'value': '/pricing', 'name': 'Pricing' },
                    { 'type': 'page', 'value': '/signup', 'name': 'Signup' },
                    { 'type': 'event', 'value': 'signup_complete', 'name': 'Complete' }
                ]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'steps' => [
                ['type' => 'page', 'value' => '/', 'name' => 'Homepage'],
                ['type' => 'page', 'value' => '/pricing', 'name' => 'Pricing'],
                ['type' => 'page', 'value' => '/signup', 'name' => 'Signup'],
                ['type' => 'event', 'value' => 'signup_complete', 'name' => 'Complete']
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          steps: [
            { type: 'page', value: '/', name: 'Homepage' },
            { type: 'page', value: '/pricing', name: 'Pricing' },
            { type: 'page', value: '/signup', name: 'Signup' },
            { type: 'event', value: 'signup_complete', name: 'Complete' }
          ]
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "bytes"
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            body := map[string]interface{}{
                "steps": []map[string]string{
                    {"type": "page", "value": "/", "name": "Homepage"},
                    {"type": "page", "value": "/pricing", "name": "Pricing"},
                    {"type": "page", "value": "/signup", "name": "Signup"},
                    {"type": "event", "value": "signup_complete", "name": "Complete"},
                },
            }
            jsonBody, _ := json.Marshal(body)

            client := &http.Client{}
            req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31", bytes.NewBuffer(jsonBody))
            req.Header.Set("Authorization", "Bearer your_api_key_here")
            req.Header.Set("Content-Type", "application/json")

            resp, _ := client.Do(req)
            defer resp.Body.Close()

            respBody, _ := io.ReadAll(resp.Body)
            var data map[string]interface{}
            json.Unmarshal(respBody, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::{json, Value};

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let body = json!({
                "steps": [
                    {"type": "page", "value": "/", "name": "Homepage"},
                    {"type": "page", "value": "/pricing", "name": "Pricing"},
                    {"type": "page", "value": "/signup", "name": "Signup"},
                    {"type": "event", "value": "signup_complete", "name": "Complete"}
                ]
            });

            let client = reqwest::Client::new();
            let response = client
                .post("https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31")
                .header("Authorization", "Bearer your_api_key_here")
                .header("Content-Type", "application/json")
                .json(&body)
                .send()
                .await?;

            let data: Value = response.json().await?;
            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        String json = """
        {
          "steps": [
            {"type": "page", "value": "/", "name": "Homepage"},
            {"type": "page", "value": "/pricing", "name": "Pricing"},
            {"type": "page", "value": "/signup", "name": "Signup"},
            {"type": "event", "value": "signup_complete", "name": "Complete"}
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        String data = response.body();
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System.Net.Http;
        using System.Net.Http.Headers;
        using System.Text;
        using System.Text.Json;

        var body = new
        {
            steps = new[]
            {
                new { type = "page", value = "/", name = "Homepage" },
                new { type = "page", value = "/pricing", name = "Pricing" },
                new { type = "page", value = "/signup", name = "Signup" },
                new { type = "event", value = "signup_complete", name = "Complete" }
            }
        };

        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync(
            "https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31",
            content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "step_number": 1,
          "step_name": "Homepage",
          "sessions": 10000,
          "conversion_rate": 100,
          "dropoff_rate": 0
        },
        {
          "step_number": 2,
          "step_name": "Pricing",
          "sessions": 4500,
          "conversion_rate": 45,
          "dropoff_rate": 55
        },
        {
          "step_number": 3,
          "step_name": "Signup",
          "sessions": 1800,
          "conversion_rate": 18,
          "dropoff_rate": 60
        },
        {
          "step_number": 4,
          "step_name": "Complete",
          "sessions": 720,
          "conversion_rate": 7.2,
          "dropoff_rate": 60
        }
      ]
    }
    ```
  </div>
</div>


# Create Funnel (/de/docs/api/funnels/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/funnels
    ```

    Creates or updates a saved funnel. If `reportId` is provided, updates the existing funnel.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Funnel name',
    type: 'string',
    required: true,
  },
  steps: {
    description: 'Array of funnel steps (minimum 2)',
    type: 'FunnelStep[]',
    required: true,
  },
  reportId: {
    description: 'Existing funnel ID to update (optional)',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the funnel was created/updated',
    type: 'boolean',
  },
  funnelId: {
    description: 'ID of the created/updated funnel',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Create New Funnel"
        curl -X POST "https://app.rybbit.io/api/sites/1/funnels" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Checkout Funnel",
            "steps": [
              { "type": "page", "value": "/products/*", "name": "Product Page" },
              { "type": "page", "value": "/cart", "name": "Cart" },
              { "type": "page", "value": "/checkout", "name": "Checkout" },
              { "type": "event", "value": "purchase", "name": "Purchase" }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Update Existing Funnel"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              reportId: 1,  // Update existing funnel
              name: 'Checkout Funnel (Updated)',
              steps: [
                { type: 'page', value: '/products/*', name: 'Product Page' },
                { type: 'page', value: '/cart', name: 'Cart' },
                { type: 'page', value: '/checkout', name: 'Checkout' },
                { type: 'page', value: '/checkout/success', name: 'Success' }
              ]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/funnels',
            json={
                'name': 'Onboarding Funnel',
                'steps': [
                    { 'type': 'page', 'value': '/signup', 'name': 'Signup' },
                    { 'type': 'event', 'value': 'account_created', 'name': 'Account Created' },
                    { 'type': 'page', 'value': '/onboarding/*', 'name': 'Onboarding' },
                    { 'type': 'event', 'value': 'onboarding_complete', 'name': 'Complete' }
                ]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Checkout Funnel',
            'steps' => [
                ['type' => 'page', 'value' => '/products/*', 'name' => 'Product Page'],
                ['type' => 'page', 'value' => '/cart', 'name' => 'Cart'],
                ['type' => 'page', 'value' => '/checkout', 'name' => 'Checkout'],
                ['type' => 'event', 'value' => 'purchase', 'name' => 'Purchase']
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Checkout Funnel',
          steps: [
            { type: 'page', value: '/products/*', name: 'Product Page' },
            { type: 'page', value: '/cart', name: 'Cart' },
            { type: 'page', value: '/checkout', name: 'Checkout' },
            { type: 'event', value: 'purchase', name: 'Purchase' }
          ]
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Checkout Funnel",
            "steps": []map[string]string{
                {"type": "page", "value": "/products/*", "name": "Product Page"},
                {"type": "page", "value": "/cart", "name": "Cart"},
                {"type": "page", "value": "/checkout", "name": "Checkout"},
                {"type": "event", "value": "purchase", "name": "Purchase"},
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Checkout Funnel",
            "steps": [
                {"type": "page", "value": "/products/*", "name": "Product Page"},
                {"type": "page", "value": "/cart", "name": "Cart"},
                {"type": "page", "value": "/checkout", "name": "Checkout"},
                {"type": "event", "value": "purchase", "name": "Purchase"}
            ]
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/1/funnels")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Checkout Funnel",
          "steps": [
            {"type": "page", "value": "/products/*", "name": "Product Page"},
            {"type": "page", "value": "/cart", "name": "Cart"},
            {"type": "page", "value": "/checkout", "name": "Checkout"},
            {"type": "event", "value": "purchase", "name": "Purchase"}
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Checkout Funnel",
            steps = new[]
            {
                new { type = "page", value = "/products/*", name = "Product Page" },
                new { type = "page", value = "/cart", name = "Cart" },
                new { type = "page", value = "/checkout", name = "Checkout" },
                new { type = "event", value = "purchase", name = "Purchase" }
            }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/funnels", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "funnelId": 2
    }
    ```
  </div>
</div>


# Delete Funnel (/de/docs/api/funnels/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/funnels/:funnelId
    ```

    Deletes a saved funnel. This action cannot be undone.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  funnelId: {
    description: 'ID of the funnel to delete',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the funnel was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/1/funnels/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels/123',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/1/funnels/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels/123')
        request = Net::HTTP::Delete.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/1/funnels/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/1/funnels/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/1/funnels/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Funnels (/de/docs/api/funnels/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/funnels
    ```

    Returns all saved funnels for a site.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of saved funnels',
    type: 'Funnel[]',
  },
}"
    />

    #### Funnel Object [#funnel-object]

    <TypeTable
      type="{
  id: {
    description: 'Unique funnel identifier',
    type: 'number',
  },
  name: {
    description: 'Funnel name',
    type: 'string',
  },
  steps: {
    description: 'Array of funnel steps',
    type: 'FunnelStep[]',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/funnels" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/funnels',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels')
        request = Net::HTTP::Get.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            client := &http.Client{}
            req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/funnels", nil)
            req.Header.Set("Authorization", "Bearer your_api_key_here")

            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)
            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();
            let response = client
                .get("https://app.rybbit.io/api/sites/1/funnels")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;
            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        String data = response.body();
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System.Net.Http;
        using System.Net.Http.Headers;

        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "your_api_key_here");

        var response = await client.GetAsync(
            "https://app.rybbit.io/api/sites/1/funnels");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "id": 1,
          "name": "Signup Funnel",
          "steps": [
            { "type": "page", "value": "/", "name": "Homepage" },
            { "type": "page", "value": "/pricing", "name": "Pricing" },
            { "type": "page", "value": "/signup", "name": "Signup" },
            { "type": "page", "value": "/signup/complete", "name": "Complete" }
          ],
          "createdAt": "2024-01-10T12:00:00.000Z",
          "updatedAt": "2024-01-15T09:30:00.000Z"
        }
      ]
    }
    ```
  </div>
</div>


# Get Funnel Step Sessions (/de/docs/api/funnels/step-sessions)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/funnels/:stepNumber/sessions
    ```

    Returns sessions that either reached or dropped off at a specific funnel step. Useful for analyzing user behavior at each stage.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  stepNumber: {
    description: 'Step number (1-indexed)',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  mode: {
    description: 'Whether to get sessions that reached or dropped off at this step',
    type: 'string',
    typeDescription: '&#x22;reached&#x22; | &#x22;dropped&#x22;',
    required: true,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 25,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  steps: {
    description: 'Array of funnel steps (same as used in analyze)',
    type: 'FunnelStep[]',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session objects',
    type: 'Session[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Get sessions that dropped off at step 2"
        curl -X POST "https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "steps": [
              { "type": "page", "value": "/", "name": "Homepage" },
              { "type": "page", "value": "/pricing", "name": "Pricing" },
              { "type": "page", "value": "/signup", "name": "Signup" }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Get sessions that reached step 3"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels/3/sessions?mode=reached&page=1',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              steps: [
                { type: 'page', value: '/', name: 'Homepage' },
                { type: 'page', value: '/pricing', name: 'Pricing' },
                { type: 'page', value: '/signup', name: 'Signup' }
              ]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/funnels/2/sessions',
            params={
                'mode': 'dropped',
                'page': 1
            },
            json={
                'steps': [
                    { 'type': 'page', 'value': '/', 'name': 'Homepage' },
                    { 'type': 'page', 'value': '/pricing', 'name': 'Pricing' },
                    { 'type': 'page', 'value': '/signup', 'name': 'Signup' }
                ]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'steps' => [
                ['type' => 'page', 'value' => '/', 'name' => 'Homepage'],
                ['type' => 'page', 'value' => '/pricing', 'name' => 'Pricing'],
                ['type' => 'page', 'value' => '/signup', 'name' => 'Signup']
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          steps: [
            { type: 'page', value: '/', name: 'Homepage' },
            { type: 'page', value: '/pricing', name: 'Pricing' },
            { type: 'page', value: '/signup', name: 'Signup' }
          ]
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "steps": []map[string]string{
                {"type": "page", "value": "/", "name": "Homepage"},
                {"type": "page", "value": "/pricing", "name": "Pricing"},
                {"type": "page", "value": "/signup", "name": "Signup"},
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "steps": [
                {"type": "page", "value": "/", "name": "Homepage"},
                {"type": "page", "value": "/pricing", "name": "Pricing"},
                {"type": "page", "value": "/signup", "name": "Signup"}
            ]
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "steps": [
            {"type": "page", "value": "/", "name": "Homepage"},
            {"type": "page", "value": "/pricing", "name": "Pricing"},
            {"type": "page", "value": "/signup", "name": "Signup"}
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            steps = new[]
            {
                new { type = "page", value = "/", name = "Homepage" },
                new { type = "page", value = "/pricing", name = "Pricing" },
                new { type = "page", value = "/signup", name = "Signup" }
            }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync(
            "https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1",
            content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "sess_abc123",
          "user_id": "user_xyz789",
          "country": "US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "entry_page": "/",
          "exit_page": "/pricing",
          "pageviews": 3,
          "session_duration": 125,
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:02:05.000Z",
          "referrer": "https://google.com",
          "channel": "organic"
        }
      ]
    }
    ```
  </div>
</div>


# Create Goal (/de/docs/api/goals/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/goals
    ```

    Creates a new goal for tracking conversions.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Goal name',
    type: 'string',
    required: false,
  },
  goalType: {
    description: 'Type of goal',
    type: 'string',
    typeDescription: '&#x22;path&#x22; | &#x22;event&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;form_submit&#x22; | &#x22;copy&#x22;',
    required: true,
  },
  config: {
    description: 'Goal configuration',
    type: 'GoalConfig',
    required: true,
  },
}"
    />

    #### GoalConfig for Path Goals [#goalconfig-for-path-goals]

    <TypeTable
      type="{
  pathPattern: {
    description: 'URL path pattern to match. Supports wildcards (*)',
    type: 'string',
    required: true,
    typeDescription: 'e.g., &#x22;/checkout/*&#x22;, &#x22;/signup/complete&#x22;',
  },
}"
    />

    #### GoalConfig for Event Goals [#goalconfig-for-event-goals]

    <TypeTable
      type="{
  eventName: {
    description: 'Event name to match',
    type: 'string',
    required: true,
  },
  eventPropertyKey: {
    description: 'Property key to match (optional)',
    type: 'string',
    required: false,
  },
  eventPropertyValue: {
    description: 'Property value to match (required if key is provided)',
    type: 'string | number | boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the goal was created',
    type: 'boolean',
  },
  goalId: {
    description: 'ID of the created goal',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Path Goal"
        curl -X POST "https://app.rybbit.io/api/sites/1/goals" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Checkout Complete",
            "goalType": "path",
            "config": {
              "pathPattern": "/checkout/success"
            }
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Event Goal"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Purchase Made',
              goalType: 'event',
              config: {
                eventName: 'purchase',
                eventPropertyKey: 'plan',
                eventPropertyValue: 'pro'
              }
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/goals',
            json={
                'name': 'Signup Complete',
                'goalType': 'path',
                'config': {
                    'pathPattern': '/signup/*'
                }
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Checkout Complete',
            'goalType' => 'path',
            'config' => [
                'pathPattern' => '/checkout/success'
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/goals')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Checkout Complete',
          goalType: 'path',
          config: { pathPattern: '/checkout/success' }
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Checkout Complete",
            "goalType": "path",
            "config": map[string]string{
                "pathPattern": "/checkout/success",
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/goals", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Checkout Complete",
            "goalType": "path",
            "config": {
                "pathPattern": "/checkout/success"
            }
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/1/goals")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Checkout Complete",
          "goalType": "path",
          "config": {
            "pathPattern": "/checkout/success"
          }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/goals"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Checkout Complete",
            goalType = "path",
            config = new { pathPattern = "/checkout/success" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/goals", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "goalId": 3
    }
    ```
  </div>
</div>


# Delete Goal (/de/docs/api/goals/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/goals/:goalId
    ```

    Deletes a goal. This action cannot be undone.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  goalId: {
    description: 'ID of the goal to delete',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the goal was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/1/goals/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals/123',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/1/goals/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/goals/123')
        request = Net::HTTP::Delete.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/1/goals/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/1/goals/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/goals/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/1/goals/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Goals (/de/docs/api/goals/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/goals
    ```

    Returns a paginated list of goals with their conversion metrics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  page_size: {
    description: 'Number of results per page (max 100)',
    type: 'number',
    default: 10,
  },
  sort: {
    description: 'Field to sort by',
    type: 'string',
    typeDescription: '&#x22;goalId&#x22; | &#x22;name&#x22; | &#x22;goalType&#x22; | &#x22;createdAt&#x22;',
    default: 'createdAt',
  },
  order: {
    description: 'Sort direction',
    type: 'string',
    typeDescription: '&#x22;asc&#x22; | &#x22;desc&#x22;',
    default: 'desc',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of goal objects with conversion data',
    type: 'Goal[]',
  },
  meta: {
    description: 'Pagination metadata',
    type: 'PaginationMeta',
  },
}"
    />

    #### Goal Object [#goal-object]

    <TypeTable
      type="{
  goalId: {
    description: 'Unique goal identifier',
    type: 'number',
  },
  name: {
    description: 'Goal name',
    type: 'string | null',
  },
  goalType: {
    description: 'Type of goal',
    type: 'string',
    typeDescription: '&#x22;path&#x22; | &#x22;event&#x22;',
  },
  config: {
    description: 'Goal configuration',
    type: 'GoalConfig',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  total_conversions: {
    description: 'Number of sessions that completed the goal',
    type: 'number',
  },
  total_sessions: {
    description: 'Total sessions in the time period',
    type: 'number',
  },
  conversion_rate: {
    description: 'Conversion rate (0-1)',
    type: 'number',
  },
}"
    />

    #### GoalConfig Object [#goalconfig-object]

    <TypeTable
      type="{
  pathPattern: {
    description: 'URL path pattern (for path goals). Supports wildcards (*)',
    type: 'string',
    required: false,
  },
  eventName: {
    description: 'Event name to match (for event goals)',
    type: 'string',
    required: false,
  },
  eventPropertyKey: {
    description: 'Event property key to match',
    type: 'string',
    required: false,
  },
  eventPropertyValue: {
    description: 'Event property value to match',
    type: 'string | number | boolean',
    required: false,
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/goals',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        <?php
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ?>
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'
        require 'uri'

        uri = URI('https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(req)
        end

        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            url := "https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31"

            req, _ := http.NewRequest("GET", url, nil)
            req.Header.Add("Authorization", "Bearer your_api_key_here")

            client := &http.Client{}
            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)

            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();

            let response = client
                .get("https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;

            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class Main {
            public static void main(String[] args) throws Exception {
                HttpClient client = HttpClient.newHttpClient();

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31"))
                    .header("Authorization", "Bearer your_api_key_here")
                    .GET()
                    .build();

                HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

                String data = response.body();
            }
        }
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System;
        using System.Net.Http;
        using System.Threading.Tasks;

        class Program
        {
            static async Task Main(string[] args)
            {
                using var client = new HttpClient();

                client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

                var response = await client.GetAsync(
                    "https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31");

                var data = await response.Content.ReadAsStringAsync();
            }
        }
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "goalId": 1,
          "name": "Signup Completed",
          "goalType": "path",
          "config": {
            "pathPattern": "/signup/complete"
          },
          "createdAt": "2024-01-10T12:00:00.000Z",
          "total_conversions": 1250,
          "total_sessions": 15420,
          "conversion_rate": 0.081
        },
        {
          "goalId": 2,
          "name": "Purchase Made",
          "goalType": "event",
          "config": {
            "eventName": "purchase",
            "eventPropertyKey": "value",
            "eventPropertyValue": 100
          },
          "createdAt": "2024-01-15T09:30:00.000Z",
          "total_conversions": 320,
          "total_sessions": 15420,
          "conversion_rate": 0.021
        }
      ],
      "meta": {
        "total": 2,
        "page": 1,
        "pageSize": 10,
        "totalPages": 1
      }
    }
    ```
  </div>
</div>


# Get Goal Sessions (/de/docs/api/goals/sessions)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/goals/:goalId/sessions
    ```

    Returns sessions that completed a specific goal. Useful for analyzing the behavior of converting users.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  goalId: {
    description: 'Goal ID',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 25,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session objects',
    type: 'Session[]',
  },
}"
    />

    #### Session Object [#session-object]

    <TypeTable
      type="{
  session_id: {
    description: 'Unique session identifier',
    type: 'string',
  },
  user_id: {
    description: 'User identifier',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  entry_page: {
    description: 'First page visited',
    type: 'string',
  },
  exit_page: {
    description: 'Last page visited',
    type: 'string',
  },
  pageviews: {
    description: 'Number of pageviews',
    type: 'number',
  },
  session_duration: {
    description: 'Session duration in seconds',
    type: 'number',
  },
  session_start: {
    description: 'Session start time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  session_end: {
    description: 'Session end time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/goals/1/sessions',
            params={
                'page': 1,
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        <?php
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ?>
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'
        require 'uri'

        uri = URI('https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(req)
        end

        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            url := "https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10"

            req, _ := http.NewRequest("GET", url, nil)
            req.Header.Add("Authorization", "Bearer your_api_key_here")

            client := &http.Client{}
            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)

            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();

            let response = client
                .get("https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;

            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class Main {
            public static void main(String[] args) throws Exception {
                HttpClient client = HttpClient.newHttpClient();

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10"))
                    .header("Authorization", "Bearer your_api_key_here")
                    .GET()
                    .build();

                HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

                String data = response.body();
            }
        }
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System;
        using System.Net.Http;
        using System.Threading.Tasks;

        class Program
        {
            static async Task Main(string[] args)
            {
                using var client = new HttpClient();

                client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

                var response = await client.GetAsync(
                    "https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10");

                var data = await response.Content.ReadAsStringAsync();
            }
        }
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "sess_abc123",
          "user_id": "user_xyz789",
          "country": "US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "entry_page": "/",
          "exit_page": "/signup/complete",
          "pageviews": 5,
          "session_duration": 245,
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:04:05.000Z",
          "referrer": "https://google.com",
          "channel": "organic"
        }
      ]
    }
    ```
  </div>
</div>


# Get Goal Time Series (/de/docs/api/goals/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/goals/time-series
    ```

    Returns goal conversions and conversion rate over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters) plus the following:

    <TypeTable
      type="{
  goal_ids: {
    description: 'The goals to include',
    type: 'string',
    typeDescription: 'Comma-separated goal IDs (e.g. &#x22;1,2&#x22;) or a JSON array. If omitted, the response is empty.',
    required: true,
  },
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
  },
}"
    />

    #### Bucket Selection Guide [#bucket-selection-guide]

    | Bucket         | Best For                             |
    | -------------- | ------------------------------------ |
    | `minute`       | Real-time monitoring (last hour)     |
    | `five_minutes` | Short-term analysis (last few hours) |
    | `hour`         | Daily analysis                       |
    | `day`          | Weekly/monthly analysis              |
    | `week`         | Monthly/quarterly analysis           |
    | `month`        | Yearly analysis                      |

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  goal_id: {
    description: 'ID of the goal',
    type: 'number',
  },
  conversions: {
    description: 'Number of distinct converting sessions in this bucket',
    type: 'number',
  },
  total_sessions: {
    description: 'Total number of sessions in this bucket',
    type: 'number',
  },
  conversion_rate: {
    description: 'Conversion rate as a fraction',
    type: 'number',
    typeDescription: 'Range: 0-1',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/goals/time-series',
            params={
                'goal_ids': '1,2',
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-01T00:00:00.000Z",
          "goal_id": 1,
          "conversions": 84,
          "total_sessions": 1250,
          "conversion_rate": 0.0672
        },
        {
          "time": "2024-01-02T00:00:00.000Z",
          "goal_id": 1,
          "conversions": 97,
          "total_sessions": 1420,
          "conversion_rate": 0.0683
        }
      ]
    }
    ```
  </div>
</div>


# Update Goal (/de/docs/api/goals/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:site/goals/:goalId
    ```

    Updates an existing goal.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  goalId: {
    description: 'ID of the goal to update',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Updated goal name',
    type: 'string',
    required: false,
  },
  goalType: {
    description: 'Type of goal',
    type: 'string',
    typeDescription: '&#x22;path&#x22; | &#x22;event&#x22;',
    required: true,
  },
  config: {
    description: 'Updated goal configuration',
    type: 'GoalConfig',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the goal was updated',
    type: 'boolean',
  },
  goalId: {
    description: 'ID of the updated goal',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/sites/1/goals/123" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Signup Completed (Updated)",
            "goalType": "path",
            "config": {
              "pathPattern": "/signup/complete/*"
            }
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals/123',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Signup Completed (Updated)',
              goalType: 'path',
              config: {
                pathPattern: '/signup/complete/*'
              }
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/sites/1/goals/123',
            json={
                'name': 'Signup Completed (Updated)',
                'goalType': 'path',
                'config': {
                    'pathPattern': '/signup/complete/*'
                }
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Signup Completed (Updated)',
            'goalType' => 'path',
            'config' => [
                'pathPattern' => '/signup/complete/*'
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/goals/123')
        request = Net::HTTP::Put.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Signup Completed (Updated)',
          goalType: 'path',
          config: { pathPattern: '/signup/complete/*' }
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Signup Completed (Updated)",
            "goalType": "path",
            "config": map[string]string{
                "pathPattern": "/signup/complete/*",
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("PUT", "https://app.rybbit.io/api/sites/1/goals/123", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Signup Completed (Updated)",
            "goalType": "path",
            "config": {
                "pathPattern": "/signup/complete/*"
            }
        });

        let client = reqwest::Client::new();
        let res = client
            .put("https://app.rybbit.io/api/sites/1/goals/123")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Signup Completed (Updated)",
          "goalType": "path",
          "config": {
            "pathPattern": "/signup/complete/*"
          }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/goals/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Signup Completed (Updated)",
            goalType = "path",
            config = new { pathPattern = "/signup/complete/*" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PutAsync("https://app.rybbit.io/api/sites/1/goals/123", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "goalId": 1
    }
    ```
  </div>
</div>


# Create Import (/de/docs/api/imports/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/imports
    ```

    Starts a new data import from a supported platform. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    Only one concurrent import is allowed per organization. Starting a second import while one is still running returns HTTP `429`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  platform: {
    description: 'Source platform to import data from',
    type: 'string',
    typeDescription: '&#x22;umami&#x22; | &#x22;simple_analytics&#x22; | &#x22;plausible&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Import details',
    type: 'CreateImportData',
  },
}"
    />

    #### CreateImportData Object [#createimportdata-object]

    <TypeTable
      type="{
  importId: {
    description: 'UUID of the created import. Use this when uploading events.',
    type: 'string',
    typeDescription: 'UUID',
  },
  allowedDateRange: {
    description: 'The inclusive date window you may import events within, based on your plan\'s retention',
    type: 'AllowedDateRange',
  },
}"
    />

    #### AllowedDateRange Object [#alloweddaterange-object]

    <TypeTable
      type="{
  earliestAllowedDate: {
    description: 'Earliest date you may import events for (inclusive)',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
  latestAllowedDate: {
    description: 'Latest date you may import events for (inclusive)',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/123/imports" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "platform": "plausible"
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              platform: 'plausible'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/123/imports',
            json={
                'platform': 'plausible'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'platform' => 'plausible'
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/imports')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          platform: 'plausible'
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "platform": "plausible",
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/123/imports", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "platform": "plausible"
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/123/imports")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "platform": "plausible"
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/imports"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            platform = "plausible"
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/123/imports", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "importId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "allowedDateRange": {
          "earliestAllowedDate": "2023-01-01",
          "latestAllowedDate": "2024-01-31"
        }
      }
    }
    ```
  </div>
</div>


# Delete Import (/de/docs/api/imports/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/imports/:importId
    ```

    Deletes an import and all events it added. The import must be finished. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    A still-running import cannot be deleted and returns HTTP `400`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  importId: {
    description: 'UUID of the import to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns `200 OK` with an empty body.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479')
        req = Net::HTTP::Delete.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479");
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Upload Import Events (/de/docs/api/imports/events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/imports/:importId/events
    ```

    Uploads a batch of raw events to an in-progress import. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    Upload events in batches. The request body limit is 50 MB, so split large exports across multiple requests. Set `isLastBatch` to `true` on the final batch to finalize the import.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  importId: {
    description: 'UUID of the import to upload events to',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  events: {
    description: 'Raw, platform-specific event objects whose shape matches the platform chosen when the import was created (Umami, Simple Analytics, or Plausible export rows)',
    type: 'object[]',
    required: true,
  },
  isLastBatch: {
    description: 'Set to true on the final batch to finalize the import',
    type: 'boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns `200 OK` with an empty body. Events outside your plan's retention window are skipped and reflected in the import's `skippedEvents` / `invalidEvents` counts (see [List Imports](/docs/api/imports/list)).
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "events": [
              { "...": "platform-specific fields" }
            ],
            "isLastBatch": false
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              events: [
                { '...': 'platform-specific fields' }
              ],
              isLastBatch: false
            })
          }
        );
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events',
            json={
                'events': [
                    { '...': 'platform-specific fields' }
                ],
                'isLastBatch': False
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'events' => [
                ['...' => 'platform-specific fields']
            ],
            'isLastBatch' => false
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          events: [
            { '...': 'platform-specific fields' }
          ],
          isLastBatch: false
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "events": []map[string]string{
                {"...": "platform-specific fields"},
            },
            "isLastBatch": false,
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "events": [
                {"...": "platform-specific fields"}
            ],
            "isLastBatch": false
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "events": [
            {"...": "platform-specific fields"}
          ],
          "isLastBatch": false
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            events = new[]
            {
                new Dictionary<string, string> { { "...", "platform-specific fields" } }
            },
            isLastBatch = false
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events", content);
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# List Imports (/de/docs/api/imports/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/imports
    ```

    Returns all data imports for a site with their progress counts. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of import objects',
    type: 'Import[]',
  },
}"
    />

    #### Import Object [#import-object]

    <TypeTable
      type="{
  importId: {
    description: 'Unique import identifier',
    type: 'string',
    typeDescription: 'UUID',
  },
  platform: {
    description: 'Source platform the data was imported from',
    type: 'string',
    typeDescription: '&#x22;umami&#x22; | &#x22;simple_analytics&#x22; | &#x22;plausible&#x22;',
  },
  importedEvents: {
    description: 'Number of events successfully imported',
    type: 'number',
  },
  skippedEvents: {
    description: 'Number of events skipped (e.g. outside the retention window)',
    type: 'number',
  },
  invalidEvents: {
    description: 'Number of events rejected as invalid',
    type: 'number',
  },
  startedAt: {
    description: 'When the import started',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  completedAt: {
    description: 'When the import finished, or null while it is still running',
    type: 'string | null',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/imports" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/imports',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        <?php
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ?>
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'
        require 'uri'

        uri = URI('https://app.rybbit.io/api/sites/123/imports')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(req)
        end

        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            url := "https://app.rybbit.io/api/sites/123/imports"

            req, _ := http.NewRequest("GET", url, nil)
            req.Header.Add("Authorization", "Bearer your_api_key_here")

            client := &http.Client{}
            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)

            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();

            let response = client
                .get("https://app.rybbit.io/api/sites/123/imports")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;

            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class Main {
            public static void main(String[] args) throws Exception {
                HttpClient client = HttpClient.newHttpClient();

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://app.rybbit.io/api/sites/123/imports"))
                    .header("Authorization", "Bearer your_api_key_here")
                    .GET()
                    .build();

                HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

                String data = response.body();
            }
        }
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System;
        using System.Net.Http;
        using System.Threading.Tasks;

        class Program
        {
            static async Task Main(string[] args)
            {
                using var client = new HttpClient();

                client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

                var response = await client.GetAsync(
                    "https://app.rybbit.io/api/sites/123/imports");

                var data = await response.Content.ReadAsStringAsync();
            }
        }
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "importId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
          "platform": "plausible",
          "importedEvents": 15420,
          "skippedEvents": 120,
          "invalidEvents": 3,
          "startedAt": "2024-01-10T12:00:00.000Z",
          "completedAt": "2024-01-10T12:04:30.000Z"
        },
        {
          "importId": "9a1c8f2e-3b7d-4e1a-9c0f-2d5b6a7e8f10",
          "platform": "umami",
          "importedEvents": 8200,
          "skippedEvents": 0,
          "invalidEvents": 0,
          "startedAt": "2024-01-15T09:30:00.000Z",
          "completedAt": null
        }
      ]
    }
    ```
  </div>
</div>


# Get Journeys (/de/docs/api/insights/journeys)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/journeys
    ```

    Returns the most common page navigation paths (user journeys) within sessions. Useful for understanding how users navigate through your site.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  steps: {
    description: 'Maximum number of steps in the journey (2-10)',
    type: 'number',
    default: 3,
  },
  limit: {
    description: 'Maximum number of journeys to return (1-500)',
    type: 'number',
    default: 100,
  },
  stepFilters: {
    description: 'JSON object to filter specific steps (e.g., {&#x22;0&#x22;: &#x22;/&#x22;})',
    type: 'string',
    typeDescription: 'JSON string mapping step index to required path',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  journeys: {
    description: 'Array of journey objects',
    type: 'Journey[]',
  },
}"
    />

    #### Journey Object [#journey-object]

    <TypeTable
      type="{
  path: {
    description: 'Array of page paths in order',
    type: 'string[]',
  },
  count: {
    description: 'Number of sessions with this journey',
    type: 'number',
  },
  percentage: {
    description: 'Percentage of total sessions',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/journeys',
            params={
                'steps': 4,
                'limit': 20,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "journeys": [
        {
          "path": ["/", "/pricing", "/signup"],
          "count": 1250,
          "percentage": 8.12
        },
        {
          "path": ["/", "/features", "/pricing", "/signup"],
          "count": 890,
          "percentage": 5.78
        },
        {
          "path": ["/blog/getting-started", "/", "/pricing"],
          "count": 650,
          "percentage": 4.22
        },
        {
          "path": ["/", "/docs", "/docs/quickstart"],
          "count": 580,
          "percentage": 3.77
        },
        {
          "path": ["/", "/about", "/contact"],
          "count": 420,
          "percentage": 2.73
        }
      ]
    }
    ```

    ### Filtering by Step [#filtering-by-step]

    You can filter journeys that include specific pages at specific steps:

    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Filter journeys starting from homepage"
        curl -X GET "https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Filter journeys starting from homepage"
        const stepFilters = JSON.stringify({ "0": "/" });

        const response = await fetch(
          `https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=${encodeURIComponent(stepFilters)}`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response with step filter"
    {
      "journeys": [
        {
          "path": ["/", "/pricing", "/signup"],
          "count": 1250,
          "percentage": 12.5
        },
        {
          "path": ["/", "/features", "/pricing"],
          "count": 890,
          "percentage": 8.9
        },
        {
          "path": ["/", "/docs", "/docs/quickstart"],
          "count": 580,
          "percentage": 5.8
        }
      ]
    }
    ```
  </div>
</div>


# Get Retention (/de/docs/api/insights/retention)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/retention
    ```

    Returns cohort-based retention analysis data. Users are grouped into cohorts based on their first visit, and retention is tracked over subsequent time periods.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  mode: {
    description: 'Retention period granularity',
    type: 'string',
    typeDescription: '&#x22;day&#x22; | &#x22;week&#x22;',
    default: 'week',
  },
  range: {
    description: 'Number of days to analyze (7-365)',
    type: 'number',
    default: 90,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Retention analysis data',
    type: 'RetentionData',
  },
}"
    />

    #### RetentionData Object [#retentiondata-object]

    <TypeTable
      type="{
  cohorts: {
    description: 'Map of cohort periods to retention data',
    type: 'Record<string, CohortData>',
  },
  maxPeriods: {
    description: 'Maximum number of retention periods',
    type: 'number',
  },
  mode: {
    description: 'Retention mode used',
    type: 'string',
    typeDescription: '&#x22;day&#x22; | &#x22;week&#x22;',
  },
  range: {
    description: 'Time range in days',
    type: 'number',
  },
}"
    />

    #### CohortData Object [#cohortdata-object]

    <TypeTable
      type="{
  size: {
    description: 'Number of users in the cohort',
    type: 'number',
  },
  percentages: {
    description: 'Retention percentages for each period (index 0 = period 0, etc.)',
    type: '(number | null)[]',
    typeDescription: 'null indicates no data for that period yet',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/retention?mode=week&range=90" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/retention?mode=week&range=90',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/retention',
            params={
                'mode': 'week',
                'range': 90
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/retention?mode=week&range=90');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/retention?mode=week&range=90')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/retention?mode=week&range=90", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "cohorts": {
          "2024-01-01": {
            "size": 1250,
            "percentages": [100, 45.2, 32.1, 28.5, 25.3, 22.1]
          },
          "2024-01-08": {
            "size": 1420,
            "percentages": [100, 48.5, 35.2, 30.1, 26.8, null]
          },
          "2024-01-15": {
            "size": 1380,
            "percentages": [100, 46.8, 33.5, 29.2, null, null]
          },
          "2024-01-22": {
            "size": 1510,
            "percentages": [100, 44.2, 31.8, null, null, null]
          },
          "2024-01-29": {
            "size": 1290,
            "percentages": [100, 47.1, null, null, null, null]
          }
        },
        "maxPeriods": 5,
        "mode": "week",
        "range": 90
      }
    }
    ```

    ### Understanding Retention Data [#understanding-retention-data]

    The retention data shows how many users from each cohort return in subsequent periods:

    * **Period 0**: Always 100% (the cohort's first visit)
    * **Period 1**: Users who returned 1 week later
    * **Period 2**: Users who returned 2 weeks later
    * etc.

    A `null` value indicates that period hasn't occurred yet for that cohort.

    ### Visualization Example [#visualization-example]

    ```javascript title="Building a Retention Table"
    const { cohorts, maxPeriods } = data.data;

    // Headers: Cohort, Size, Week 0, Week 1, Week 2, ...
    const headers = ['Cohort', 'Size',
      ...Array(maxPeriods + 1).fill(0).map((_, i) => `Week ${i}`)
    ];

    // Rows
    Object.entries(cohorts).forEach(([date, cohort]) => {
      const row = [
        date,
        cohort.size,
        ...cohort.percentages.map(p => p !== null ? `${p}%` : '-')
      ];
      console.log(row.join(' | '));
    });
    ```
  </div>
</div>


# Add Organization Member (/de/docs/api/organizations/add-member)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/members
    ```

    Adds a user to an organization with a specified role. The user must already exist in the system. Requires admin or owner role in the organization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  email: {
    description: 'Email address of the user to add',
    type: 'string',
    typeDescription: 'Must match an existing user',
    required: true,
  },
  role: {
    description: 'Role to assign to the user',
    type: 'string',
    typeDescription: '&#x22;admin&#x22; | &#x22;member&#x22; | &#x22;owner&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns a success message when the user is added successfully.

    <TypeTable
      type="{
  message: {
    description: 'Success message',
    type: 'string',
  },
}"
    />

    ### Error Responses [#error-responses]

    <TypeTable
      type="{
  '400': {
    description: 'Invalid input (missing fields, invalid role, or user already a member)',
    type: 'object',
  },
  '401': {
    description: 'Unauthorized (not an admin/owner of the organization)',
    type: 'object',
  },
  '404': {
    description: 'User not found',
    type: 'object',
  },
  '500': {
    description: 'Internal server error',
    type: 'object',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_123/members" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"email": "newuser@example.com", "role": "member"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/members`,
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              email: 'newuser@example.com',
              role: 'member'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_123'
        response = requests.post(
            f'https://app.rybbit.io/api/organizations/{organization_id}/members',
            json={
                'email': 'newuser@example.com',
                'role': 'member'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/members");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'email' => 'newuser@example.com',
            'role' => 'member'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/members")
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = {
          email: 'newuser@example.com',
          role: 'member'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_123"
        body := bytes.NewBuffer([]byte(`{
          "email": "newuser@example.com",
          "role": "member"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/"+organizationId+"/members", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_123";
        let client = reqwest::Client::new();
        let res = client
            .post(format!("https://app.rybbit.io/api/organizations/{}/members", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "email": "newuser@example.com",
                "role": "member"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_123";
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"email\": \"newuser@example.com\", \"role\": \"member\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/members"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"email\": \"newuser@example.com\", \"role\": \"member\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"https://app.rybbit.io/api/organizations/{organizationId}/members", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "message": "User added to organization successfully"
    }
    ```

    ```json title="Error Response (400 - Already a Member)"
    {
      "error": "User is already a member of this organization"
    }
    ```

    ```json title="Error Response (404 - User Not Found)"
    {
      "error": "User not found"
    }
    ```

    ```json title="Error Response (401 - Unauthorized)"
    {
      "error": "Unauthorized"
    }
    ```
  </div>
</div>


# Create Site (/de/docs/api/organizations/create-site)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/sites
    ```

    Creates a new site within an organization. Requires admin or owner role in the organization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID to add the site to',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  domain: {
    description: 'Site domain',
    type: 'string',
    typeDescription: 'Valid domain format (e.g., example.com)',
    required: true,
  },
  name: {
    description: 'Site display name',
    type: 'string',
    required: true,
  },
  public: {
    description: 'Make analytics publicly accessible',
    type: 'boolean',
    default: false,
  },
  saltUserIds: {
    description: 'Salt user IDs for privacy',
    type: 'boolean',
    default: false,
  },
  blockBots: {
    description: 'Block bot traffic',
    type: 'boolean',
    default: true,
  },
  excludedIPs: {
    description: 'Array of IP addresses to exclude from tracking',
    type: 'string[]',
    default: '[]',
  },
  excludedCountries: {
    description: 'Array of ISO country codes to exclude (e.g., [&#x22;US&#x22;, &#x22;GB&#x22;])',
    type: 'string[]',
    default: '[]',
  },
  sessionReplay: {
    description: 'Enable session replay recording',
    type: 'boolean',
    default: false,
  },
  webVitals: {
    description: 'Enable Core Web Vitals tracking',
    type: 'boolean',
    default: false,
  },
  trackErrors: {
    description: 'Enable JavaScript error tracking',
    type: 'boolean',
    default: false,
  },
  trackOutbound: {
    description: 'Track outbound link clicks',
    type: 'boolean',
    default: true,
  },
  trackUrlParams: {
    description: 'Track URL parameters (UTM, etc.)',
    type: 'boolean',
    default: true,
  },
  trackInitialPageView: {
    description: 'Automatically track the initial page view',
    type: 'boolean',
    default: true,
  },
  trackSpaNavigation: {
    description: 'Track SPA navigation events',
    type: 'boolean',
    default: true,
  },
  trackIp: {
    description: 'Store visitor IP addresses',
    type: 'boolean',
    default: false,
  },
  trackButtonClicks: {
    description: 'Track button click events',
    type: 'boolean',
    default: false,
  },
  trackCopy: {
    description: 'Track copy events',
    type: 'boolean',
    default: false,
  },
  trackFormInteractions: {
    description: 'Track form interaction events',
    type: 'boolean',
    default: false,
  },
  tags: {
    description: 'Array of tags for organizing the site',
    type: 'string[]',
    default: '[]',
  },
}"
    />

    ### Response [#response]

    Returns the created site object with the assigned `siteId`.

    <TypeTable
      type="{
  siteId: {
    description: 'Numeric site ID (auto-assigned)',
    type: 'number',
  },
  id: {
    description: 'Site UUID',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string',
  },
  createdBy: {
    description: 'User ID who created the site',
    type: 'string',
  },
  public: {
    description: 'Whether analytics are public',
    type: 'boolean',
  },
  saltUserIds: {
    description: 'Whether user IDs are salted',
    type: 'boolean',
  },
  blockBots: {
    description: 'Whether bot traffic is blocked',
    type: 'boolean',
  },
  excludedIPs: {
    description: 'Excluded IP addresses',
    type: 'string[]',
  },
  excludedCountries: {
    description: 'Excluded country codes',
    type: 'string[]',
  },
  sessionReplay: {
    description: 'Whether session replay is enabled',
    type: 'boolean',
  },
  webVitals: {
    description: 'Whether Web Vitals tracking is enabled',
    type: 'boolean',
  },
  trackErrors: {
    description: 'Whether error tracking is enabled',
    type: 'boolean',
  },
  trackOutbound: {
    description: 'Whether outbound link tracking is enabled',
    type: 'boolean',
  },
  trackUrlParams: {
    description: 'Whether URL parameter tracking is enabled',
    type: 'boolean',
  },
  trackInitialPageView: {
    description: 'Whether initial page view is tracked automatically',
    type: 'boolean',
  },
  trackSpaNavigation: {
    description: 'Whether SPA navigation is tracked',
    type: 'boolean',
  },
  trackIp: {
    description: 'Whether IP addresses are stored',
    type: 'boolean',
  },
  trackButtonClicks: {
    description: 'Whether button clicks are tracked',
    type: 'boolean',
  },
  trackCopy: {
    description: 'Whether copy events are tracked',
    type: 'boolean',
  },
  trackFormInteractions: {
    description: 'Whether form interactions are tracked',
    type: 'boolean',
  },
  tags: {
    description: 'Site tags',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_123/sites" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"domain": "example.com", "name": "My Website", "blockBots": true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/sites`,
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              domain: 'example.com',
              name: 'My Website',
              blockBots: true
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_123'
        response = requests.post(
            f'https://app.rybbit.io/api/organizations/{organization_id}/sites',
            json={
                'domain': 'example.com',
                'name': 'My Website',
                'blockBots': True
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/sites");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'domain' => 'example.com',
            'name' => 'My Website',
            'blockBots' => true
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/sites")
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = {
          domain: 'example.com',
          name: 'My Website',
          blockBots: true
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_123"
        body := bytes.NewBuffer([]byte(`{
          "domain": "example.com",
          "name": "My Website",
          "blockBots": true
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/"+organizationId+"/sites", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_123";
        let client = reqwest::Client::new();
        let res = client
            .post(format!("https://app.rybbit.io/api/organizations/{}/sites", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "domain": "example.com",
                "name": "My Website",
                "blockBots": true
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_123";
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"domain\": \"example.com\", \"name\": \"My Website\", \"blockBots\": true}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/sites"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"domain\": \"example.com\", \"name\": \"My Website\", \"blockBots\": true}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"https://app.rybbit.io/api/organizations/{organizationId}/sites", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "siteId": 456,
      "id": "a1b2c3d4e5f6",
      "domain": "example.com",
      "name": "My Website",
      "organizationId": "org_123",
      "createdBy": "user_xyz789",
      "public": false,
      "saltUserIds": false,
      "blockBots": true,
      "excludedIPs": [],
      "excludedCountries": [],
      "sessionReplay": false,
      "webVitals": false,
      "trackErrors": false,
      "trackOutbound": true,
      "trackUrlParams": true,
      "trackInitialPageView": true,
      "trackSpaNavigation": true,
      "trackIp": false,
      "trackButtonClicks": false,
      "trackCopy": false,
      "trackFormInteractions": false,
      "tags": []
    }
    ```
  </div>
</div>


# Get Organization Event Count (/de/docs/api/organizations/event-count)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/org-event-count/:organizationId
    ```

    Returns daily event usage counts across an organization's sites.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  start_date: {
    description: 'Start of the date range. Omit start/end to get all-time daily counts.',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
  end_date: {
    description: 'End of the date range. Omit start/end to get all-time daily counts.',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
  time_zone: {
    description: 'IANA timezone used to bucket events into days',
    type: 'string',
    default: 'UTC',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  event_date: {
    description: 'The day the counts apply to',
    type: 'string',
  },
  pageview_count: {
    description: 'Number of pageview events',
    type: 'number',
  },
  custom_event_count: {
    description: 'Number of custom events',
    type: 'number',
  },
  performance_count: {
    description: 'Number of performance events',
    type: 'number',
  },
  outbound_count: {
    description: 'Number of outbound link events',
    type: 'number',
  },
  error_count: {
    description: 'Number of error events',
    type: 'number',
  },
  button_click_count: {
    description: 'Number of button click events',
    type: 'number',
  },
  copy_count: {
    description: 'Number of copy events',
    type: 'number',
  },
  form_submit_count: {
    description: 'Number of form submit events',
    type: 'number',
  },
  input_change_count: {
    description: 'Number of input change events',
    type: 'number',
  },
  event_count: {
    description: 'Total number of events for the day',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/org-event-count/org_abc123?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/org-event-count/${organizationId}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.get(
            f'https://app.rybbit.io/api/org-event-count/{organization_id}',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'UTC'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/org-event-count/{$organizationId}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/org-event-count/#{organization_id}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/org-event-count/"+organizationId+"?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/org-event-count/{}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/org-event-count/" + organizationId + "?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/org-event-count/{organizationId}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "event_date": "2024-01-01",
          "pageview_count": 38900,
          "custom_event_count": 4210,
          "performance_count": 12050,
          "outbound_count": 980,
          "error_count": 145,
          "button_click_count": 6320,
          "copy_count": 410,
          "form_submit_count": 220,
          "input_change_count": 1530,
          "event_count": 64765
        },
        {
          "event_date": "2024-01-02",
          "pageview_count": 41200,
          "custom_event_count": 4560,
          "performance_count": 12880,
          "outbound_count": 1040,
          "error_count": 132,
          "button_click_count": 6710,
          "copy_count": 455,
          "form_submit_count": 248,
          "input_change_count": 1622,
          "event_count": 68847
        }
      ]
    }
    ```
  </div>
</div>


# Invite Member (/de/docs/api/organizations/invite-member)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/organization/invite-member
    ```

    Sends an invitation email inviting a user to join an organization with a given role. (To add an existing user directly without an email invite, see Add Member.)

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  email: {
    description: 'Email address of the user to invite',
    type: 'string',
    required: true,
  },
  role: {
    description: 'Role(s) to assign. One of `owner`, `admin`, `member` (or an array of roles).',
    type: 'string | string[]',
    required: true,
  },
  organizationId: {
    description: 'The organization to invite into. Defaults to your active organization.',
    type: 'string',
    required: false,
  },
  resend: {
    description: 'Resend the invitation if the user was already invited.',
    type: 'boolean',
    required: false,
  },
  teamId: {
    description: 'Team ID(s) to add the invited user to.',
    type: 'string | string[]',
    required: false,
  },
  hasRestrictedSiteAccess: {
    description: 'Rybbit extension: restrict the invited member to specific sites. Only valid when role is `member`.',
    type: 'boolean',
    required: false,
  },
  siteIds: {
    description: 'Rybbit extension: the site IDs the member may access when `hasRestrictedSiteAccess` is true.',
    type: 'number[]',
    required: false,
  },
}"
    />

    <Callout>
      `hasRestrictedSiteAccess`

       and 

      `siteIds`

       are Rybbit-specific extensions to the invitation. Site-access restrictions can only be applied to invitations with the 

      `member`

       role.
    </Callout>

    ### Response [#response]

    Returns the created invitation object.

    <TypeTable
      type="{
  id: {
    description: &#x22;The invitation's identifier&#x22;,
    type: 'string',
  },
  email: {
    description: 'Invited email address',
    type: 'string',
  },
  role: {
    description: 'Assigned role',
    type: 'string',
  },
  organizationId: {
    description: 'The organization the invite is for',
    type: 'string',
  },
  inviterId: {
    description: 'ID of the user who sent the invite',
    type: 'string',
  },
  status: {
    description: 'Invitation status (e.g. pending)',
    type: 'string',
  },
  expiresAt: {
    description: 'When the invitation expires',
    type: 'string',
  },
  hasRestrictedSiteAccess: {
    description: 'Whether the member will be restricted to specific sites',
    type: 'boolean',
  },
  siteIds: {
    description: 'Site IDs the member will be allowed to access',
    type: 'number[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/organization/invite-member" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"email": "teammate@example.com", "role": "member"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/organization/invite-member',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              email: 'teammate@example.com',
              role: 'member'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/organization/invite-member',
            json={
                'email': 'teammate@example.com',
                'role': 'member'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/organization/invite-member");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'email' => 'teammate@example.com',
            'role' => 'member'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/organization/invite-member")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          email: 'teammate@example.com',
          role: 'member'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "email": "teammate@example.com",
          "role": "member"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/organization/invite-member", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/organization/invite-member")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "email": "teammate@example.com",
                "role": "member"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"email\": \"teammate@example.com\", \"role\": \"member\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/organization/invite-member"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"email\": \"teammate@example.com\", \"role\": \"member\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/organization/invite-member", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "inv_4a2b...",
      "email": "teammate@example.com",
      "role": "member",
      "organizationId": "org_123",
      "inviterId": "user_2a9b...",
      "status": "pending",
      "expiresAt": "2026-07-03T12:00:00.000Z",
      "hasRestrictedSiteAccess": false,
      "siteIds": []
    }
    ```
  </div>
</div>


# Get My Organizations (/de/docs/api/organizations/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations
    ```

    Returns all organizations the authenticated user is a member of, including all members for each organization. Excludes subscription and billing information. Supports both session cookies and API key (Bearer token) authentication.

    <Callout type="warn">
      The 

      `members`

       roster is only populated for session-cookie (dashboard) requests. API key / Bearer callers receive 

      `members: []`

       for every organization — use 

      [GET /organizations/:id/members](/docs/api/organizations/members)

       to retrieve member data with a key.
    </Callout>

    ### Response [#response]

    Returns an array of organization objects.

    <TypeTable
      type="{
  id: {
    description: 'Organization ID',
    type: 'string',
  },
  name: {
    description: 'Organization name',
    type: 'string',
  },
  slug: {
    description: 'Organization slug',
    type: 'string',
  },
  logo: {
    description: 'Organization logo URL',
    type: 'string | null',
  },
  createdAt: {
    description: 'Organization creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  role: {
    description: 'Your role in the organization',
    type: 'string',
    typeDescription: '&#x22;owner&#x22; | &#x22;admin&#x22; | &#x22;member&#x22;',
  },
  members: {
    description: 'Array of organization members',
    type: 'array',
  },
  sites: {
    description: 'Array of sites in the organization',
    type: 'array',
  },
}"
    />

    #### Member Object [#member-object]

    Each member in the `members` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Member record ID',
    type: 'string',
  },
  role: {
    description: 'Member role in the organization',
    type: 'string',
    typeDescription: '&#x22;owner&#x22; | &#x22;admin&#x22; | &#x22;member&#x22;',
  },
  userId: {
    description: 'User ID',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when member was added',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  user: {
    description: 'User details',
    type: 'object',
  },
}"
    />

    #### User Object [#user-object]

    <TypeTable
      type="{
  id: {
    description: 'User ID',
    type: 'string',
  },
  name: {
    description: 'User display name',
    type: 'string',
  },
  email: {
    description: 'User email address',
    type: 'string',
  },
}"
    />

    #### Site Object [#site-object]

    Each site in the `sites` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Site ID',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string',
  },
  createdBy: {
    description: 'User ID who created the site',
    type: 'string',
  },
  public: {
    description: 'Whether analytics are publicly accessible',
    type: 'boolean',
  },
  saltUserIds: {
    description: 'Whether user IDs are salted',
    type: 'boolean',
  },
  blockBots: {
    description: 'Whether bot traffic is blocked',
    type: 'boolean',
  },
  createdAt: {
    description: 'Site creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/organizations',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/organizations')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data []map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/organizations")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/organizations");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    [
      {
        "id": "org_123",
        "name": "Acme Inc",
        "slug": "acme-inc",
        "logo": "https://example.com/logo.png",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "role": "owner",
        "members": [
          {
            "id": "member_abc123",
            "role": "owner",
            "userId": "user_xyz789",
            "createdAt": "2024-01-15T10:30:00.000Z",
            "user": {
              "id": "user_xyz789",
              "name": "John Doe",
              "email": "john@example.com"
            }
          },
          {
            "id": "member_def456",
            "role": "member",
            "userId": "user_abc456",
            "createdAt": "2024-02-20T14:15:00.000Z",
            "user": {
              "id": "user_abc456",
              "name": "Jane Smith",
              "email": "jane@example.com"
            }
          }
        ],
        "sites": [
          {
            "id": "456",
            "domain": "example.com",
            "name": "My Website",
            "organizationId": "org_123",
            "createdBy": "user_xyz789",
            "public": false,
            "saltUserIds": false,
            "blockBots": true,
            "createdAt": "2024-01-15T10:30:00.000Z"
          }
        ]
      },
      {
        "id": "org_456",
        "name": "Tech Startup",
        "slug": "tech-startup",
        "logo": null,
        "createdAt": "2024-03-10T08:00:00.000Z",
        "role": "admin",
        "members": [
          {
            "id": "member_ghi789",
            "role": "owner",
            "userId": "user_owner123",
            "createdAt": "2024-03-10T08:00:00.000Z",
            "user": {
              "id": "user_owner123",
              "name": "Alice Johnson",
              "email": "alice@techstartup.com"
            }
          },
          {
            "id": "member_jkl012",
            "role": "admin",
            "userId": "user_xyz789",
            "createdAt": "2024-03-12T09:30:00.000Z",
            "user": {
              "id": "user_xyz789",
              "name": "John Doe",
              "email": "john@example.com"
            }
          }
        ],
        "sites": [
          {
            "id": "789",
            "domain": "techstartup.com",
            "name": "Tech Startup Website",
            "organizationId": "org_456",
            "createdBy": "user_owner123",
            "public": true,
            "saltUserIds": false,
            "blockBots": true,
            "createdAt": "2024-03-10T08:00:00.000Z"
          }
        ]
      }
    ]
    ```
  </div>
</div>


# Get Organization Members (/de/docs/api/organizations/members)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations/:organizationId/members
    ```

    Returns all members of an organization with their user details and roles. Requires membership in the organization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  data: {
    description: 'Array of organization members',
    type: 'array',
  },
}"
    />

    #### Member Object [#member-object]

    Each member in the `data` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Member record ID',
    type: 'string',
  },
  role: {
    description: 'Member role in the organization',
    type: 'string',
    typeDescription: '&#x22;owner&#x22; | &#x22;admin&#x22; | &#x22;member&#x22;',
  },
  userId: {
    description: 'User ID',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when member was added',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  user: {
    description: 'User details',
    type: 'object',
  },
  siteAccess: {
    description: &#x22;The member's site-access restrictions within the organization&#x22;,
    type: 'object',
  },
  teams: {
    description: 'Teams the member belongs to',
    type: 'array',
  },
}"
    />

    #### User Object [#user-object]

    <TypeTable
      type="{
  id: {
    description: 'User ID',
    type: 'string',
  },
  name: {
    description: 'User display name',
    type: 'string',
  },
  email: {
    description: 'User email address',
    type: 'string',
  },
}"
    />

    #### Site Access Object [#site-access-object]

    <TypeTable
      type="{
  hasRestrictedSiteAccess: {
    description: 'Whether the member is restricted to specific sites',
    type: 'boolean',
  },
  siteIds: {
    description: 'IDs of the sites the member can access (empty when access is not restricted)',
    type: 'array',
  },
}"
    />

    #### Team Object [#team-object]

    Each team in the `teams` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Team ID',
    type: 'string',
  },
  name: {
    description: 'Team name',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations/org_123/members" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/members`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_123'
        response = requests.get(
            f'https://app.rybbit.io/api/organizations/{organization_id}/members',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/members");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/members")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations/"+organizationId+"/members", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/organizations/{}/members", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/members"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/organizations/{organizationId}/members");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": [
        {
          "id": "member_abc123",
          "role": "owner",
          "userId": "user_xyz789",
          "organizationId": "org_123",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "user": {
            "id": "user_xyz789",
            "name": "John Doe",
            "email": "john@example.com"
          },
          "siteAccess": {
            "hasRestrictedSiteAccess": false,
            "siteIds": []
          },
          "teams": []
        },
        {
          "id": "member_def456",
          "role": "member",
          "userId": "user_abc456",
          "organizationId": "org_123",
          "createdAt": "2024-02-20T14:15:00.000Z",
          "user": {
            "id": "user_abc456",
            "name": "Jane Smith",
            "email": "jane@example.com"
          },
          "siteAccess": {
            "hasRestrictedSiteAccess": true,
            "siteIds": ["456"]
          },
          "teams": [
            {
              "id": "team_789",
              "name": "Marketing"
            }
          ]
        }
      ]
    }
    ```
  </div>
</div>


# Remove Member (/de/docs/api/organizations/remove-member)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/organization/remove-member
    ```

    Removes a member from an organization. The member can be identified by member ID or email.

    <Callout type="warn">
      This endpoint uses 

      **POST**

      , not HTTP DELETE. You cannot remove the only remaining owner of an organization.
    </Callout>

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  memberIdOrEmail: {
    description: &#x22;The member's ID or email address&#x22;,
    type: 'string',
    required: true,
  },
  organizationId: {
    description: 'The organization to remove from. Defaults to your active organization.',
    type: 'string',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the removed member object.

    <TypeTable
      type="{
  member: {
    description: 'The member that was removed',
    type: 'Member',
  },
}"
    />

    #### Member Object [#member-object]

    <TypeTable
      type="{
  id: {
    description: &#x22;The member record's identifier&#x22;,
    type: 'string',
  },
  userId: {
    description: &#x22;The underlying user's ID&#x22;,
    type: 'string',
  },
  organizationId: {
    description: 'The organization the member belonged to',
    type: 'string',
  },
  role: {
    description: &#x22;The member's role&#x22;,
    type: 'string',
  },
  createdAt: {
    description: 'When the membership was created',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/organization/remove-member" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"memberIdOrEmail": "teammate@example.com"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/organization/remove-member',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              memberIdOrEmail: 'teammate@example.com'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/organization/remove-member',
            json={
                'memberIdOrEmail': 'teammate@example.com'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/organization/remove-member");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'memberIdOrEmail' => 'teammate@example.com'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/organization/remove-member")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          memberIdOrEmail: 'teammate@example.com'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "memberIdOrEmail": "teammate@example.com"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/organization/remove-member", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/organization/remove-member")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "memberIdOrEmail": "teammate@example.com"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"memberIdOrEmail\": \"teammate@example.com\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/organization/remove-member"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"memberIdOrEmail\": \"teammate@example.com\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/organization/remove-member", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "member": {
        "id": "mem_7c6d...",
        "userId": "user_5f4g...",
        "organizationId": "org_123",
        "role": "member",
        "createdAt": "2026-01-10T12:00:00.000Z"
      }
    }
    ```
  </div>
</div>


# Get Organization Sites (/de/docs/api/organizations/sites)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations/:organizationId/sites
    ```

    Returns all sites in an organization the caller can access, with usage and subscription info.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  organization: {
    description: 'The organization record, or null',
    type: 'object | null',
  },
  sites: {
    description: 'Array of site objects',
    type: 'array',
  },
  subscription: {
    description: 'Usage and subscription details for the organization',
    type: 'object',
  },
}"
    />

    #### Site Object [#site-object]

    Each site in the `sites` array contains the following fields. Other site-config fields may also be present:

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'number',
  },
  name: {
    description: 'Site display name',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  type: {
    description: 'Site type',
    type: 'string',
    typeDescription: 'e.g. &#x22;web&#x22;',
  },
  public: {
    description: 'Whether the site dashboard is public',
    type: 'boolean',
  },
  organizationId: {
    description: 'Organization ID the site belongs to',
    type: 'string',
  },
  sessionsLast24Hours: {
    description: 'Number of sessions in the last 24 hours',
    type: 'number',
  },
  isOwner: {
    description: 'Whether the caller owns the site',
    type: 'boolean',
  },
  teams: {
    description: 'Teams the site belongs to',
    type: 'array',
    typeDescription: 'Array of { id, name }',
  },
}"
    />

    #### Subscription Object [#subscription-object]

    <TypeTable
      type="{
  monthlyEventCount: {
    description: 'Events recorded in the current month',
    type: 'number',
  },
  eventLimit: {
    description: 'Monthly event limit for the plan',
    type: 'number',
  },
  overMonthlyLimit: {
    description: 'Whether the monthly event limit has been exceeded',
    type: 'boolean',
  },
  planName: {
    description: 'Name of the active plan',
    type: 'string',
  },
  status: {
    description: 'Subscription status',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations/org_abc123/sites" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/sites`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.get(
            f'https://app.rybbit.io/api/organizations/{organization_id}/sites',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/sites");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/sites")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations/"+organizationId+"/sites", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/organizations/{}/sites", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/sites"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/organizations/{organizationId}/sites");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "organization": {
        "id": "org_abc123",
        "name": "Acme Inc",
        "slug": "acme",
        "createdAt": "2024-01-15T10:30:00.000Z"
      },
      "sites": [
        {
          "siteId": 123,
          "name": "Acme Marketing",
          "domain": "acme.com",
          "type": "web",
          "public": false,
          "organizationId": "org_abc123",
          "sessionsLast24Hours": 842,
          "isOwner": true,
          "teams": [
            {
              "id": "team_xyz789",
              "name": "Growth"
            }
          ]
        }
      ],
      "subscription": {
        "monthlyEventCount": 482910,
        "eventLimit": 1000000,
        "overMonthlyLimit": false,
        "planName": "Pro",
        "status": "active"
      }
    }
    ```
  </div>
</div>


# Update Member Role (/de/docs/api/organizations/update-member-role)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/organization/update-member-role
    ```

    Updates the role(s) assigned to an existing organization member.

    <Callout>
      This endpoint uses 

      **POST**

      , not PUT or PATCH.
    </Callout>

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  role: {
    description: 'The new role(s) to assign. One of `owner`, `admin`, `member` (or an array of roles).',
    type: 'string | string[]',
    required: true,
  },
  memberId: {
    description: 'The ID of the member to update',
    type: 'string',
    required: true,
  },
  organizationId: {
    description: 'The organization the member belongs to. Defaults to your active organization.',
    type: 'string',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the updated member object directly — the fields are at the top level, **not** nested under a `member` key.

    <TypeTable
      type="{
  id: {
    description: &#x22;The member record's identifier&#x22;,
    type: 'string',
  },
  userId: {
    description: &#x22;The underlying user's ID&#x22;,
    type: 'string',
  },
  organizationId: {
    description: 'The organization the member belongs to',
    type: 'string',
  },
  role: {
    description: &#x22;The member's updated role&#x22;,
    type: 'string',
  },
  createdAt: {
    description: 'When the membership was created',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/organization/update-member-role" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"memberId": "mem_7c6d5e4f3g2h", "role": "admin"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/organization/update-member-role',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              memberId: 'mem_7c6d5e4f3g2h',
              role: 'admin'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/organization/update-member-role',
            json={
                'memberId': 'mem_7c6d5e4f3g2h',
                'role': 'admin'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/organization/update-member-role");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'memberId' => 'mem_7c6d5e4f3g2h',
            'role' => 'admin'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/organization/update-member-role")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          memberId: 'mem_7c6d5e4f3g2h',
          role: 'admin'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "memberId": "mem_7c6d5e4f3g2h",
          "role": "admin"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/organization/update-member-role", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/organization/update-member-role")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "memberId": "mem_7c6d5e4f3g2h",
                "role": "admin"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"memberId\": \"mem_7c6d5e4f3g2h\", \"role\": \"admin\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/organization/update-member-role"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"memberId\": \"mem_7c6d5e4f3g2h\", \"role\": \"admin\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/organization/update-member-role", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "mem_7c6d5e4f3g2h",
      "userId": "user_5f4g...",
      "organizationId": "org_123",
      "role": "admin",
      "createdAt": "2026-01-10T12:00:00.000Z"
    }
    ```
  </div>
</div>


# Get Live Visitors (/de/docs/api/overview/live-visitors)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/live-user-count
    ```

    Returns the count of unique active visitors within the specified time window. Useful for displaying real-time visitor counts.

    Visitors are counted by identity where one is available (see [Identify Users](/docs/identify-users)) and by anonymous device otherwise, so one person who starts a second session inside the window still counts once.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  minutes: {
    description: 'Time window in minutes to count active visitors',
    type: 'number',
    default: 5,
    typeDescription: 'Visitors with activity within the last N minutes are considered &#x22;live&#x22;',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  count: {
    description: 'Number of unique active visitors',
    type: 'number',
  },
}"
    />

    #### Time Window Guide [#time-window-guide]

    | Minutes | Use Case                                  |
    | ------- | ----------------------------------------- |
    | `1`     | Very active visitors (currently browsing) |
    | `5`     | Standard "live" count (default)           |
    | `15`    | Recently active visitors                  |
    | `30`    | Short-term engagement window              |
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/live-user-count?minutes=5" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/live-user-count?minutes=5',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const { count } = await response.json();
        console.log(`Live visitors: ${count}`);
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/live-user-count',
            params={'minutes': 5},
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        print(f"Live visitors: {data['count']}")
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/live-user-count?minutes=5');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        echo "Live visitors: " . $data['count'];
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/live-user-count?minutes=5')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        puts "Live visitors: #{data['count']}"
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/live-user-count?minutes=5", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        fmt.Printf("Live visitors: %v\n", data["count"])
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/live-user-count?minutes=5")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        println!("Live visitors: {}", data["count"]);
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/live-user-count?minutes=5"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/live-user-count?minutes=5");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "count": 42
    }
    ```

    ### Polling Example [#polling-example]

    ```javascript title="Real-time Widget"
    async function updateLiveCount() {
      const response = await fetch(
        'https://app.rybbit.io/api/sites/123/live-user-count?minutes=5',
        {
          headers: {
            'Authorization': 'Bearer your_api_key'
          }
        }
      );
      const { count } = await response.json();
      document.getElementById('live-visitors')
        .textContent = count;
    }

    // Update every 15 seconds
    setInterval(updateLiveCount, 15000);
    ```
  </div>
</div>


# Get Metric (/de/docs/api/overview/metric)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/metric
    ```

    Returns dimensional analytics data broken down by a specific parameter. Supports pagination.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  parameter: {
    description: 'The dimension to break down by',
    type: 'FilterParameter',
    typeDescription: 'e.g., &#x22;pathname&#x22;, &#x22;country&#x22;, &#x22;browser&#x22;, &#x22;event_name&#x22;',
    required: true,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of metric results',
    type: 'MetricItem[]',
    typeDescription: 'See MetricItem structure below',
  },
  totalCount: {
    description: 'Total number of unique values across all pages',
    type: 'number',
  },
}"
    />

    #### MetricItem Structure [#metricitem-structure]

    <TypeTable
      type="{
  value: {
    description: 'The dimension value',
    type: 'string',
    typeDescription: 'e.g., &#x22;/blog&#x22;, &#x22;Chrome&#x22;, &#x22;US&#x22;',
  },
  count: {
    description: 'Number of unique sessions for this value. For parameter=event_name, this is the total number of event occurrences instead',
    type: 'number',
  },
  percentage: {
    description: 'Percentage of total sessions',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  pageviews: {
    description: 'Total pageviews (for page-related parameters)',
    type: 'number',
    required: false,
  },
  pageviews_percentage: {
    description: 'Share of total pageviews (for page-related parameters)',
    type: 'number',
    typeDescription: 'Range: 0-100',
    required: false,
  },
  bounce_rate: {
    description: 'Bounce rate percentage',
    type: 'number',
    typeDescription: 'Range: 0-100',
    required: false,
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/metric',
            params={
                'parameter': 'country',
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York',
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "data": [
          {
            "value": "US",
            "count": 8420,
            "percentage": 54.63,
            "pageviews": 26891,
            "pageviews_percentage": 54.96,
            "bounce_rate": 41.2
          },
          {
            "value": "GB",
            "count": 2150,
            "percentage": 13.95,
            "pageviews": 6847,
            "pageviews_percentage": 13.99,
            "bounce_rate": 43.8
          }
        ],
        "totalCount": 87
      }
    }
    ```
  </div>
</div>


# Get Overview (/de/docs/api/overview/overview)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/overview
    ```

    Returns high-level analytics metrics for a site.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  sessions: {
    description: 'Total number of sessions',
    type: 'number',
  },
  pageviews: {
    description: 'Total number of pageviews',
    type: 'number',
  },
  users: {
    description: 'Total unique users',
    type: 'number',
  },
  pages_per_session: {
    description: 'Average pages viewed per session',
    type: 'number',
  },
  bounce_rate: {
    description: 'Percentage of single-page sessions',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  session_duration: {
    description: 'Average session duration in seconds',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/overview',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "sessions": 15420,
        "pageviews": 48933,
        "users": 12847,
        "pages_per_session": 3.17,
        "bounce_rate": 42.8,
        "session_duration": 182.5
      }
    }
    ```
  </div>
</div>


# Get Page Titles (/de/docs/api/overview/page-titles)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/page-titles
    ```

    Returns page-view metrics aggregated by HTML page title.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    <TypeTable
      type="{
  limit: {
    description: 'Maximum number of page titles to return',
    type: 'number',
    default: 10,
  },
  page: {
    description: 'Page number (1-indexed). When provided, the response is paginated and includes a total count',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  value: {
    description: 'The page title',
    type: 'string',
  },
  pathname: {
    description: 'A representative path for the title',
    type: 'string',
  },
  count: {
    description: 'Unique sessions that viewed the title',
    type: 'number',
  },
  percentage: {
    description: 'Share of total',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  pageviews: {
    description: 'Total pageviews',
    type: 'number',
  },
  bounce_rate: {
    description: 'Bounce rate percentage',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  time_on_page_seconds: {
    description: 'Average time on page in seconds',
    type: 'number',
  },
}"
    />

    When the `page` parameter is supplied, the response is paginated: `data` becomes an object `{ data: [...], totalCount: number }`.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/page-titles',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York',
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "value": "Home | Acme",
          "pathname": "/",
          "count": 8200,
          "percentage": 41.2,
          "pageviews": 12400,
          "bounce_rate": 38.5,
          "time_on_page_seconds": 47.2
        }
      ]
    }
    ```
  </div>
</div>


# Get Overview (Time Series) (/de/docs/api/overview/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/overview/time-series
    ```

    Returns time-series analytics data broken down by configurable time buckets. Useful for charting trends over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    required: false,
    default: 'hour',
  },
}"
    />

    #### Bucket Selection Guide [#bucket-selection-guide]

    | Bucket         | Best For                             |
    | -------------- | ------------------------------------ |
    | `minute`       | Real-time monitoring (last hour)     |
    | `five_minutes` | Short-term analysis (last few hours) |
    | `hour`         | Daily analysis                       |
    | `day`          | Weekly/monthly analysis              |
    | `week`         | Monthly/quarterly analysis           |
    | `month`        | Yearly analysis                      |

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'Datetime string, &#x22;YYYY-MM-DD HH:MM:SS&#x22;',
  },
  sessions: {
    description: 'Number of sessions in this bucket',
    type: 'number',
  },
  pageviews: {
    description: 'Number of pageviews in this bucket',
    type: 'number',
  },
  users: {
    description: 'Unique users in this bucket',
    type: 'number',
  },
  pages_per_session: {
    description: 'Average pages viewed per session',
    type: 'number',
  },
  bounce_rate: {
    description: 'Percentage of single-page sessions',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  session_duration: {
    description: 'Average session duration in seconds',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/overview/time-series',
            params={
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-01 00:00:00",
          "sessions": 1250,
          "pageviews": 3890,
          "users": 1100,
          "pages_per_session": 3.11,
          "bounce_rate": 41.5,
          "session_duration": 165.2
        },
        {
          "time": "2024-01-02 00:00:00",
          "sessions": 1420,
          "pageviews": 4520,
          "users": 1280,
          "pages_per_session": 3.18,
          "bounce_rate": 39.8,
          "session_duration": 178.4
        },
        {
          "time": "2024-01-03 00:00:00",
          "sessions": 1380,
          "pageviews": 4210,
          "users": 1190,
          "pages_per_session": 3.05,
          "bounce_rate": 42.1,
          "session_duration": 162.8
        }
      ]
    }
    ```
  </div>
</div>


# Get Performance by Dimension (/de/docs/api/performance/by-dimension)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/performance/by-dimension
    ```

    Returns performance metrics broken down by a specific dimension (page, country, browser, etc.). Useful for identifying performance issues on specific pages or for specific user segments.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  dimension: {
    description: 'Dimension to break down by',
    type: 'string',
    typeDescription: '&#x22;pathname&#x22; | &#x22;country&#x22; | &#x22;device_type&#x22; | &#x22;browser&#x22; | &#x22;operating_system&#x22; | &#x22;region&#x22;',
    required: true,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    required: false,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  sort_by: {
    description: 'Field to sort by',
    type: 'string',
    default: 'event_count',
  },
  sort_order: {
    description: 'Sort direction',
    type: 'string',
    typeDescription: '&#x22;asc&#x22; | &#x22;desc&#x22;',
    default: 'desc',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Paginated response object',
    type: 'PaginatedResponse',
  },
}"
    />

    #### DimensionPerformance Object [#dimensionperformance-object]

    Each object includes the dimension value plus all percentiles:

    <TypeTable
      type="{
  pathname: {
    description: 'The dimension value (field name matches dimension param)',
    type: 'string',
  },
  event_count: {
    description: 'Number of performance events',
    type: 'number',
  },
  lcp_avg: {
    description: 'Average LCP',
    type: 'number',
  },
  lcp_p50: {
    description: 'LCP 50th percentile',
    type: 'number',
  },
  lcp_p75: {
    description: 'LCP 75th percentile',
    type: 'number',
  },
  lcp_p90: {
    description: 'LCP 90th percentile',
    type: 'number',
  },
  lcp_p99: {
    description: 'LCP 99th percentile',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/performance/by-dimension',
            params={
                'dimension': 'pathname',
                'sort_by': 'lcp_p75',
                'sort_order': 'desc',
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "data": [
          {
            "pathname": "/dashboard",
            "event_count": 12450,
            "lcp_avg": 2850,
            "lcp_p50": 2400,
            "lcp_p75": 3200,
            "lcp_p90": 4100,
            "lcp_p99": 6500,
            "cls_avg": 0.08,
            "cls_p50": 0.05,
            "cls_p75": 0.12,
            "inp_avg": 180,
            "inp_p50": 150,
            "inp_p75": 220,
            "fcp_avg": 1450,
            "fcp_p50": 1300,
            "fcp_p75": 1700,
            "ttfb_avg": 520,
            "ttfb_p50": 480,
            "ttfb_p75": 680
          },
          {
            "pathname": "/reports",
            "event_count": 8920,
            "lcp_avg": 2650,
            "lcp_p50": 2200,
            "lcp_p75": 2900,
            "lcp_p90": 3800,
            "lcp_p99": 5800
          }
        ],
        "totalCount": 156
      }
    }
    ```
  </div>
</div>


# Get Performance Overview (/de/docs/api/performance/overview)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/performance/overview
    ```

    Returns aggregate performance metrics with percentile breakdowns for all Core Web Vitals.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Performance metrics object',
    type: 'PerformanceMetrics',
  },
}"
    />

    #### PerformanceMetrics Object [#performancemetrics-object]

    Each metric (lcp, cls, inp, fcp, ttfb) includes the following percentiles:

    <TypeTable
      type="{
  lcp_p50: {
    description: 'LCP 50th percentile (median)',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  lcp_p75: {
    description: 'LCP 75th percentile',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  lcp_p90: {
    description: 'LCP 90th percentile',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  lcp_p99: {
    description: 'LCP 99th percentile',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  total_performance_events: {
    description: 'Total number of performance measurements',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/performance/overview',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "lcp_p50": 1850,
        "lcp_p75": 2400,
        "lcp_p90": 3200,
        "lcp_p99": 5100,
        "cls_p50": 0.05,
        "cls_p75": 0.1,
        "cls_p90": 0.18,
        "cls_p99": 0.35,
        "inp_p50": 120,
        "inp_p75": 180,
        "inp_p90": 280,
        "inp_p99": 450,
        "fcp_p50": 1200,
        "fcp_p75": 1600,
        "fcp_p90": 2100,
        "fcp_p99": 3500,
        "ttfb_p50": 450,
        "ttfb_p75": 650,
        "ttfb_p90": 950,
        "ttfb_p99": 1800,
        "total_performance_events": 48521
      }
    }
    ```
  </div>
</div>


# Get Performance Time Series (/de/docs/api/performance/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/performance/time-series
    ```

    Returns performance metrics over time, broken down by configurable time buckets. Useful for charting performance trends.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data. Defaults to &#x22;hour&#x22; when omitted.',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of time-bucketed performance data',
    type: 'PerformancePoint[]',
  },
}"
    />

    #### PerformancePoint Object [#performancepoint-object]

    Each point includes all percentiles for each metric plus:

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  event_count: {
    description: 'Number of performance events in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/performance/time-series',
            params={
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'UTC'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-01T00:00:00.000Z",
          "lcp_p50": 1820,
          "lcp_p75": 2350,
          "lcp_p90": 3100,
          "lcp_p99": 4900,
          "cls_p50": 0.04,
          "cls_p75": 0.09,
          "inp_p50": 115,
          "inp_p75": 175,
          "fcp_p50": 1180,
          "fcp_p75": 1580,
          "ttfb_p50": 440,
          "ttfb_p75": 640,
          "event_count": 6892
        },
        {
          "time": "2024-01-02T00:00:00.000Z",
          "lcp_p50": 1900,
          "lcp_p75": 2450,
          "lcp_p90": 3250,
          "lcp_p99": 5200,
          "cls_p50": 0.05,
          "cls_p75": 0.11,
          "inp_p50": 125,
          "inp_p75": 185,
          "fcp_p50": 1220,
          "fcp_p75": 1620,
          "ttfb_p50": 460,
          "ttfb_p75": 660,
          "event_count": 7234
        }
      ]
    }
    ```
  </div>
</div>


# Create Segment (/de/docs/api/segments/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/segments
    ```

    Creates a saved segment. Members create site segments they own; admins and owners can also create organization-wide segments.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Segment name (1–80 characters)',
    type: 'string',
    required: true,
  },
  filters: {
    description: 'Filters that define the segment (1–20). Validated with the same schema as the `filters` parameter',
    type: 'Filter[]',
    typeDescription: 'See Filter Parameters in Getting Started',
    required: true,
  },
  description: {
    description: 'Optional notes (up to 500 characters)',
    type: 'string | null',
    required: false,
  },
  scope: {
    description: 'Where the segment is available. Organization-wide segments require an admin or owner',
    type: 'string',
    typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;',
    default: 'site',
    required: false,
  },
  isPublic: {
    description: 'Show on the public dashboard and private links',
    type: 'boolean',
    default: 'false',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created segment with status 201.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/1/segments" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"name": "Mobile organic from Germany", "filters": [{"parameter": "device_type", "type": "equals", "value": ["Mobile"]}, {"parameter": "channel", "type": "equals", "value": ["Organic Search"]}, {"parameter": "country", "type": "equals", "value": ["DE"]}]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({"name": "Mobile organic from Germany", "filters": [{"parameter": "device_type", "type": "equals", "value": ["Mobile"]}, {"parameter": "channel", "type": "equals", "value": ["Organic Search"]}, {"parameter": "country", "type": "equals", "value": ["DE"]}]})
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/segments',
            json={"name": "Mobile organic from Germany", "filters": [{"parameter": "device_type", "type": "equals", "value": ["Mobile"]}, {"parameter": "channel", "type": "equals", "value": ["Organic Search"]}, {"parameter": "country", "type": "equals", "value": ["DE"]}]},
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "segmentId": 12,
      "siteId": 1,
      "organizationId": "org_abc123",
      "userId": "user_xyz",
      "name": "Mobile organic from Germany",
      "description": null,
      "filters": [
        { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
        { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
        { "parameter": "country", "type": "equals", "value": ["DE"] }
      ],
      "isPublic": false,
      "type": "segment",
      "canEdit": true,
      "createdAt": "2026-09-02T10:15:00.000Z",
      "updatedAt": "2026-09-02T10:15:00.000Z"
    }
    ```
  </div>
</div>


# Delete Segment (/de/docs/api/segments/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/segments/:segmentId
    ```

    Deletes a saved segment. Admins and owners can delete any segment; members can delete segments they created. Links that already expanded the segment's filters keep working.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  segmentId: {
    description: 'Segment ID',
    type: 'number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the segment was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/1/segments/12" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments/12',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/1/segments/12',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Segment (/de/docs/api/segments/get)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/segments/:segmentId
    ```

    Returns one saved segment.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  segmentId: {
    description: 'Segment ID',
    type: 'number',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns the segment.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/segments/12" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments/12',
          {
            method: 'GET',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/segments/12',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "segmentId": 12,
      "siteId": 1,
      "organizationId": "org_abc123",
      "userId": "user_xyz",
      "name": "Mobile organic from Germany",
      "description": null,
      "filters": [
        { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
        { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
        { "parameter": "country", "type": "equals", "value": ["DE"] }
      ],
      "isPublic": false,
      "type": "segment",
      "canEdit": true,
      "createdAt": "2026-09-02T10:15:00.000Z",
      "updatedAt": "2026-09-02T10:15:00.000Z"
    }
    ```
  </div>
</div>


# Get Segments (/de/docs/api/segments/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/segments
    ```

    Returns the saved segments available on a site: its own plus organization-wide ones. Callers without site access only see segments shown on the public dashboard.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns an array of segments, sorted by name.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/segments" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments',
          {
            method: 'GET',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/segments',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    [
      {
        "segmentId": 12,
        "siteId": 1,
        "organizationId": "org_abc123",
        "userId": "user_xyz",
        "name": "Mobile organic from Germany",
        "description": null,
        "filters": [
          { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
          { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
          { "parameter": "country", "type": "equals", "value": ["DE"] }
        ],
        "isPublic": false,
        "type": "segment",
        "canEdit": true,
        "createdAt": "2026-09-02T10:15:00.000Z",
        "updatedAt": "2026-09-02T10:15:00.000Z"
      }
    ]
    ```
  </div>
</div>


# Update Segment (/de/docs/api/segments/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:site/segments/:segmentId
    ```

    Updates a saved segment. Admins and owners can edit any segment; members can edit segments they created. Only the fields you send change.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  segmentId: {
    description: 'Segment ID',
    type: 'number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Segment name (1–80 characters)',
    type: 'string',
    required: false,
  },
  filters: {
    description: 'Filters that define the segment (1–20). Validated with the same schema as the `filters` parameter',
    type: 'Filter[]',
    typeDescription: 'See Filter Parameters in Getting Started',
    required: false,
  },
  description: {
    description: 'Optional notes (up to 500 characters)',
    type: 'string | null',
    required: false,
  },
  scope: {
    description: 'Where the segment is available. Organization-wide segments require an admin or owner',
    type: 'string',
    typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;',
    default: 'site',
    required: false,
  },
  isPublic: {
    description: 'Show on the public dashboard and private links',
    type: 'boolean',
    default: 'false',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the updated segment.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/sites/1/segments/12" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"name": "Mobile organic (DE)", "isPublic": true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments/12',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({"name": "Mobile organic (DE)", "isPublic": true})
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/sites/1/segments/12',
            json={"name": "Mobile organic (DE)", "isPublic": true},
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "segmentId": 12,
      "siteId": 1,
      "organizationId": "org_abc123",
      "userId": "user_xyz",
      "name": "Mobile organic (DE)",
      "description": null,
      "filters": [
        { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
        { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
        { "parameter": "country", "type": "equals", "value": ["DE"] }
      ],
      "isPublic": true,
      "type": "segment",
      "canEdit": true,
      "createdAt": "2026-09-02T10:15:00.000Z",
      "updatedAt": "2026-09-02T10:15:00.000Z"
    }
    ```
  </div>
</div>


# Delete Session Replay (/de/docs/api/session-replay/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/session-replay/:sessionId
    ```

    Permanently deletes a session replay recording. Requires site write access.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  sessionId: {
    description: 'The session to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the deletion was successful',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
        req = Net::HTTP::Delete.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Session Replay Events (/de/docs/api/session-replay/events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/session-replay/:sessionId
    ```

    Returns the rrweb events and metadata needed to reconstruct a session replay.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  sessionId: {
    description: 'The session to fetch',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  events: {
    description: 'Array of rrweb event objects, replayed in order to reconstruct the session. Each carries a timestamp and rrweb-format payload.',
    type: 'RRWebEvent[]',
  },
  metadata: {
    description: &#x22;The session replay metadata object (same fields as a list item, enriched with the user's traits)&#x22;,
    type: 'SessionReplayMetadata',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "events": [
        {
          "type": 4,
          "timestamp": 1705320000000,
          "data": { }
        }
      ],
      "metadata": {
        "session_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "duration_ms": 48200,
        "event_count": 312,
        "browser": "Chrome",
        "...": "..."
      }
    }
    ```
  </div>
</div>


# Get Session Replays (/de/docs/api/session-replay/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/session-replay/list
    ```

    Returns recorded session replays with metadata, newest first.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters) plus the following:

    <TypeTable
      type="{
  limit: {
    description: 'Number of results to return',
    type: 'number',
    default: 50,
  },
  offset: {
    description: 'Number of results to skip',
    type: 'number',
    default: 0,
  },
  userId: {
    description: 'Restrict to a single user',
    type: 'string',
    required: false,
  },
  minDuration: {
    description: 'Minimum replay duration in seconds',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session replay objects',
    type: 'SessionReplay[]',
  },
}"
    />

    #### SessionReplay Object [#sessionreplay-object]

    Identified users are enriched with their `traits`.

    <TypeTable
      type="{
  session_id: {
    description: 'Unique session identifier',
    type: 'string',
  },
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  start_time: {
    description: 'Replay start time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  end_time: {
    description: 'Replay end time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  duration_ms: {
    description: 'Duration in milliseconds',
    type: 'number',
  },
  page_url: {
    description: 'Entry page',
    type: 'string',
  },
  event_count: {
    description: 'Number of recorded events',
    type: 'number',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/session-replay/list',
            params={
                'limit': 50,
                'offset': 0,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
          "user_id": "dev_xyz789",
          "identified_user_id": "user@example.com",
          "start_time": "2024-01-31T14:00:00.000Z",
          "end_time": "2024-01-31T14:00:48.200Z",
          "duration_ms": 48200,
          "page_url": "/",
          "event_count": 312,
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "browser": "Chrome",
          "browser_version": "120.0.0",
          "operating_system": "macOS",
          "operating_system_version": "14.2",
          "device_type": "desktop",
          "screen_width": 1920,
          "screen_height": 1080
        }
      ]
    }
    ```
  </div>
</div>


# Get Session (/de/docs/api/sessions/get)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/sessions/:sessionId
    ```

    Returns detailed information about a specific session including all events and pageviews.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  sessionId: {
    description: 'Session ID',
    type: 'string',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  limit: {
    description: 'Number of events to return',
    type: 'number',
    default: 100,
  },
  offset: {
    description: 'Number of events to skip',
    type: 'number',
    default: 0,
  },
  minutes: {
    description: 'Only return events from the last N minutes',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Session details object',
    type: 'SessionDetails',
  },
}"
    />

    #### SessionDetails Object [#sessiondetails-object]

    <TypeTable
      type="{
  session: {
    description: 'Session metadata',
    type: 'SessionMeta',
  },
  events: {
    description: 'Array of events in the session',
    type: 'Event[]',
  },
  pagination: {
    description: 'Pagination info for events',
    type: 'Pagination',
  },
}"
    />

    #### Event Object [#event-object]

    <TypeTable
      type="{
  timestamp: {
    description: 'Event timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
  },
  hostname: {
    description: 'Hostname',
    type: 'string',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;error&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;copy&#x22; | &#x22;form_submit&#x22; | &#x22;input_change&#x22;',
  },
  event_name: {
    description: 'Custom event name (for custom_event type)',
    type: 'string',
  },
  props: {
    description: 'Event properties',
    type: 'object',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/sessions/sess_abc123',
            params={'limit': 50},
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "session": {
          "session_id": "sess_abc123",
          "user_id": "dev_xyz789",
          "country": "US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:04:05.000Z",
          "session_duration": 245,
          "pageviews": 5,
          "events": 7,
          "entry_page": "/",
          "exit_page": "/pricing"
        },
        "events": [
          {
            "timestamp": "2024-01-31T14:00:00.000Z",
            "pathname": "/",
            "hostname": "example.com",
            "page_title": "Home",
            "type": "pageview",
            "referrer": "https://google.com"
          },
          {
            "timestamp": "2024-01-31T14:01:30.000Z",
            "pathname": "/",
            "hostname": "example.com",
            "type": "custom_event",
            "event_name": "cta_click",
            "props": { "button": "hero" }
          }
        ],
        "pagination": {
          "total": 7,
          "limit": 50,
          "offset": 0,
          "hasMore": false
        }
      }
    }
    ```
  </div>
</div>


# Get Sessions (/de/docs/api/sessions/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/sessions
    ```

    Returns a paginated list of sessions with their analytics data.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  user_id: {
    description: 'Filter sessions by user ID',
    type: 'string',
    required: false,
  },
  identified_only: {
    description: 'Only return sessions from identified users',
    type: 'string',
    typeDescription: '&#x22;true&#x22; | &#x22;false&#x22;',
    default: 'false',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session objects',
    type: 'Session[]',
  },
}"
    />

    #### Session Object [#session-object]

    <TypeTable
      type="{
  session_id: {
    description: 'Unique session identifier',
    type: 'string',
  },
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  traits: {
    description: 'Custom user traits',
    type: 'object | null',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
  },
  channel: {
    description: 'Traffic channel',
    type: 'string',
  },
  entry_page: {
    description: 'First page visited',
    type: 'string',
  },
  exit_page: {
    description: 'Last page visited',
    type: 'string',
  },
  pageviews: {
    description: 'Number of pageviews',
    type: 'number',
  },
  events: {
    description: 'Number of custom events',
    type: 'number',
  },
  session_duration: {
    description: 'Duration in seconds',
    type: 'number',
  },
  session_start: {
    description: 'Session start time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  session_end: {
    description: 'Session end time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  utm_source: {
    description: 'UTM source parameter',
    type: 'string',
  },
  utm_medium: {
    description: 'UTM medium parameter',
    type: 'string',
  },
  utm_campaign: {
    description: 'UTM campaign parameter',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/sessions',
            params={
                'page': 1,
                'limit': 20,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "sess_abc123",
          "user_id": "dev_xyz789",
          "identified_user_id": "user@example.com",
          "traits": { "plan": "pro" },
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "referrer": "https://google.com",
          "channel": "organic",
          "entry_page": "/",
          "exit_page": "/pricing",
          "pageviews": 5,
          "events": 2,
          "session_duration": 245,
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:04:05.000Z",
          "utm_source": "google",
          "utm_medium": "cpc",
          "utm_campaign": "brand"
        }
      ]
    }
    ```
  </div>
</div>


# Get Session Locations (/de/docs/api/sessions/locations)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/sessions/locations
    ```

    Returns aggregated session locations with coordinates for map visualization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of location objects',
    type: 'Location[]',
  },
}"
    />

    #### Location Object [#location-object]

    <TypeTable
      type="{
  lat: {
    description: 'Latitude coordinate',
    type: 'number',
  },
  lon: {
    description: 'Longitude coordinate',
    type: 'number',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  count: {
    description: 'Number of sessions from this location',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/sessions/locations',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "lat": 37.7749,
          "lon": -122.4194,
          "city": "San Francisco",
          "country": "US",
          "count": 1250
        },
        {
          "lat": 40.7128,
          "lon": -74.006,
          "city": "New York",
          "country": "US",
          "count": 980
        },
        {
          "lat": 51.5074,
          "lon": -0.1278,
          "city": "London",
          "country": "GB",
          "count": 650
        }
      ]
    }
    ```
  </div>
</div>


# Create Team (/de/docs/api/teams/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/teams
    ```

    Creates a team in an organization. Requires admin/owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Team name',
    type: 'string',
    required: true,
  },
  memberUserIds: {
    description: 'User IDs to add to the team (must be members of the organization)',
    type: 'string[]',
    required: false,
  },
  siteIds: {
    description: 'Site IDs the team can access (must belong to the organization)',
    type: 'number[]',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created team with HTTP 201.

    <TypeTable
      type="{
  id: {
    description: 'Team ID',
    type: 'string',
  },
  name: {
    description: 'Team name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID the team belongs to',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when the team was created',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Timestamp when the team was last updated',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  members: {
    description: 'Array of added user IDs',
    type: 'string[]',
  },
  siteIds: {
    description: 'Array of granted site IDs',
    type: 'number[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_abc123/teams" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"name": "Marketing", "memberUserIds": ["user_123"], "siteIds": [123]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/teams`,
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Marketing',
              memberUserIds: ['user_123'],
              siteIds: [123]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.post(
            f'https://app.rybbit.io/api/organizations/{organization_id}/teams',
            json={
                'name': 'Marketing',
                'memberUserIds': ['user_123'],
                'siteIds': [123]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/teams");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'name' => 'Marketing',
            'memberUserIds' => ['user_123'],
            'siteIds' => [123]
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/teams")
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = {
          name: 'Marketing',
          memberUserIds: ['user_123'],
          siteIds: [123]
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        body := bytes.NewBuffer([]byte(`{
          "name": "Marketing",
          "memberUserIds": ["user_123"],
          "siteIds": [123]
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/"+organizationId+"/teams", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .post(format!("https://app.rybbit.io/api/organizations/{}/teams", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "name": "Marketing",
                "memberUserIds": ["user_123"],
                "siteIds": [123]
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"name\": \"Marketing\", \"memberUserIds\": [\"user_123\"], \"siteIds\": [123]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/teams"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"name\": \"Marketing\", \"memberUserIds\": [\"user_123\"], \"siteIds\": [123]}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"https://app.rybbit.io/api/organizations/{organizationId}/teams", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "team_xyz789",
      "name": "Marketing",
      "organizationId": "org_abc123",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "members": ["user_123"],
      "siteIds": [123]
    }
    ```
  </div>
</div>


# Delete Team (/de/docs/api/teams/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/organizations/:organizationId/teams/:teamId
    ```

    Deletes a team. Requires admin/owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
  teamId: {
    description: 'ID of the team to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the team was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789')
        request = Net::HTTP::Delete.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Teams (/de/docs/api/teams/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations/:organizationId/teams
    ```

    Returns the teams in an organization, with their members and accessible sites.

    Any organization member may call this. Members who are not an admin/owner only see the teams they belong to.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  teams: {
    description: 'Array of teams in the organization',
    type: 'array',
  },
}"
    />

    #### Team Object [#team-object]

    Each team in the `teams` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Team ID',
    type: 'string',
  },
  name: {
    description: 'Team name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID the team belongs to',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when the team was created',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Timestamp when the team was last updated',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  members: {
    description: 'Members of the team',
    type: 'array',
  },
  sites: {
    description: 'Sites the team can access',
    type: 'array',
  },
}"
    />

    #### Member Object [#member-object]

    <TypeTable
      type="{
  userId: {
    description: 'User ID',
    type: 'string',
  },
  userName: {
    description: 'User display name',
    type: 'string',
  },
  userEmail: {
    description: 'User email address',
    type: 'string',
  },
}"
    />

    #### Site Object [#site-object]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'number',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations/org_abc123/teams" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/teams`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.get(
            f'https://app.rybbit.io/api/organizations/{organization_id}/teams',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/teams");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/teams")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations/"+organizationId+"/teams", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/organizations/{}/teams", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/teams"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/organizations/{organizationId}/teams");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "teams": [
        {
          "id": "team_xyz789",
          "name": "Marketing",
          "organizationId": "org_abc123",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "updatedAt": "2024-02-20T14:15:00.000Z",
          "members": [
            {
              "userId": "user_123",
              "userName": "John Doe",
              "userEmail": "john@example.com"
            }
          ],
          "sites": [
            {
              "siteId": 123,
              "domain": "example.com",
              "name": "Example Site"
            }
          ]
        }
      ]
    }
    ```
  </div>
</div>


# Update Team (/de/docs/api/teams/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/organizations/:organizationId/teams/:teamId
    ```

    Updates a team's name, members, or site access. Requires admin/owner role.

    When `memberUserIds` or `siteIds` is provided, it **replaces** the team's entire existing set (it is not merged). Omit a field to leave it unchanged.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
  teamId: {
    description: 'ID of the team to update',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Updated team name',
    type: 'string',
    required: false,
  },
  memberUserIds: {
    description: 'User IDs to set as the team members (replaces the existing set)',
    type: 'string[]',
    required: false,
  },
  siteIds: {
    description: 'Site IDs to set as the team site access (replaces the existing set)',
    type: 'number[]',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the team was updated',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Growth",
            "memberUserIds": ["user_123", "user_456"]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Growth',
              memberUserIds: ['user_123', 'user_456']
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
            json={
                'name': 'Growth',
                'memberUserIds': ['user_123', 'user_456']
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Growth',
            'memberUserIds' => ['user_123', 'user_456']
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789')
        request = Net::HTTP::Put.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Growth',
          memberUserIds: ['user_123', 'user_456']
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Growth",
            "memberUserIds": []string{"user_123", "user_456"},
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("PUT", "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Growth",
            "memberUserIds": ["user_123", "user_456"]
        });

        let client = reqwest::Client::new();
        let res = client
            .put("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Growth",
          "memberUserIds": ["user_123", "user_456"]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Growth",
            memberUserIds = new[] { "user_123", "user_456" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PutAsync("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Delete Site (/de/docs/api/sites/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:siteId
    ```

    Permanently deletes a site and all its associated data. This action cannot be undone. Requires admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the deletion was successful',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123')
        req = Net::HTTP::Delete.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Excluded Countries (/de/docs/api/sites/excluded-countries)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId/excluded-countries
    ```

    Returns the list of country codes that are excluded from tracking.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedCountries: {
    description: 'Array of excluded country codes (2-letter ISO codes)',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-countries" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-countries',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-countries',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-countries');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-countries')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-countries", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-countries")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-countries"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-countries");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedCountries": [
        "CN",
        "RU",
        "KP"
      ]
    }
    ```
  </div>
</div>


# Get Excluded Hostnames (/de/docs/api/sites/excluded-hostnames)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/excluded-hostnames
    ```

    Returns the list of hostnames excluded from analytics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedHostnames: {
    description: 'Array of excluded hostnames',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-hostnames" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-hostnames',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-hostnames',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-hostnames');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-hostnames')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-hostnames", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-hostnames")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-hostnames"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-hostnames");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedHostnames": [
        "staging.example.com"
      ]
    }
    ```
  </div>
</div>


# Get Excluded IPs (/de/docs/api/sites/excluded-ips)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId/excluded-ips
    ```

    Returns the list of IP addresses and CIDR ranges that are excluded from tracking.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedIPs: {
    description: 'Array of excluded IP addresses or CIDR ranges',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-ips" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-ips',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-ips',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-ips');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-ips')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-ips", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-ips")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-ips"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-ips");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedIPs": [
        "192.168.1.1",
        "10.0.0.0/8",
        "172.16.0.0/12"
      ]
    }
    ```
  </div>
</div>


# Get Excluded Paths (/de/docs/api/sites/excluded-paths)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/excluded-paths
    ```

    Returns the list of URL paths excluded from analytics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedPaths: {
    description: 'Array of excluded URL paths',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-paths" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-paths',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-paths',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-paths');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-paths')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-paths", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-paths")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-paths"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-paths");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedPaths": [
        "/admin",
        "/internal/*"
      ]
    }
    ```
  </div>
</div>


# Get Excluded User Agents (/de/docs/api/sites/excluded-user-agents)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/excluded-user-agents
    ```

    Returns the list of user-agent patterns excluded from analytics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedUserAgents: {
    description: 'Array of excluded user-agent patterns',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-user-agents" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-user-agents',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-user-agents',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-user-agents');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-user-agents')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-user-agents", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-user-agents")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-user-agents"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-user-agents");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedUserAgents": [
        "*HeadlessChrome*"
      ]
    }
    ```
  </div>
</div>


# Export PDF Report (/de/docs/api/sites/export-pdf)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/export/pdf
    ```

    Generates a downloadable PDF analytics report for a date range.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  start_date: {
    description: 'Start of the date range',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
    required: true,
  },
  end_date: {
    description: 'End of the date range',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
    required: true,
  },
  time_zone: {
    description: 'IANA timezone',
    type: 'string',
    required: true,
  },
  filters: {
    description: 'JSON-encoded filter array (same format as the Common Parameters filters)',
    type: 'string',
  },
}"
    />

    ### Response [#response]

    Returns a binary PDF file (`Content-Type: application/pdf`). Save the response body to a `.pdf` file rather than parsing it as JSON.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here" \
          -o report.pdf
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const blob = await response.blob();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/export/pdf',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        with open('report.pdf', 'wb') as f:
            f.write(response.content)
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        file_put_contents('report.pdf', $response);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'

        uri = URI('https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        File.binwrite('report.pdf', res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        out, _ := os.Create("report.pdf")
        defer out.Close()
        io.Copy(out, resp.Body)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let bytes = res.bytes().await?;
        std::fs::write("report.pdf", &bytes)?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<Path> response = client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("report.pdf")));
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var bytes = await response.Content.ReadAsByteArrayAsync();
        File.WriteAllBytes("report.pdf", bytes);
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Get Private Link Config (/de/docs/api/sites/get-private-link)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId/private-link-config
    ```

    Returns the private link key configuration. Private links allow sharing analytics with a secret key without requiring authentication.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  data: {
    description: 'Private link configuration',
    type: 'object',
  },
}"
    />

    #### Data Object [#data-object]

    <TypeTable
      type="{
  privateLinkKey: {
    description: 'Private link key, or null if not generated',
    type: 'string | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/private-link-config" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/private-link-config',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/private-link-config',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/private-link-config');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/private-link-config')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/private-link-config", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/private-link-config")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/private-link-config"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/private-link-config");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": {
        "privateLinkKey": "a1b2c3d4e5f6"
      }
    }
    ```
  </div>
</div>


# Get Site (/de/docs/api/sites/get)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId
    ```

    Returns detailed information about a specific site including its configuration.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  id: {
    description: 'Site UUID',
    type: 'string | null',
  },
  siteId: {
    description: 'Numeric site ID',
    type: 'number',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  createdBy: {
    description: 'User ID who created the site',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string | null',
  },
  public: {
    description: 'Whether the site analytics are publicly accessible',
    type: 'boolean',
  },
  saltUserIds: {
    description: 'Whether user IDs are salted for privacy',
    type: 'boolean',
  },
  blockBots: {
    description: 'Whether bot traffic is blocked',
    type: 'boolean',
  },
  isOwner: {
    description: 'Whether the current user owns this site',
    type: 'boolean',
  },
  sessionReplay: {
    description: 'Whether session replay is enabled',
    type: 'boolean',
  },
  webVitals: {
    description: 'Whether Web Vitals tracking is enabled',
    type: 'boolean',
  },
  trackErrors: {
    description: 'Whether error tracking is enabled',
    type: 'boolean',
  },
  trackOutbound: {
    description: 'Whether outbound link tracking is enabled',
    type: 'boolean',
  },
  trackUrlParams: {
    description: 'Whether URL parameter tracking is enabled',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "site_abc123",
      "siteId": 123,
      "name": "My Website",
      "domain": "example.com",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-31T14:00:00.000Z",
      "createdBy": "user_xyz789",
      "organizationId": "org_def456",
      "public": false,
      "saltUserIds": false,
      "blockBots": true,
      "isOwner": true,
      "sessionReplay": true,
      "webVitals": true,
      "trackErrors": true,
      "trackOutbound": true,
      "trackUrlParams": false
    }
    ```
  </div>
</div>


# Get Site Has Data (/de/docs/api/sites/has-data)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/has-data
    ```

    Returns whether the site has received any analytics events.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  hasData: {
    description: 'Whether the site has received any analytics events',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/has-data" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/has-data',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/has-data',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/has-data');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/has-data')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/has-data", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/has-data")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/has-data"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/has-data");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "hasData": true
    }
    ```
  </div>
</div>


# Get Site Public Status (/de/docs/api/sites/is-public)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/is-public
    ```

    Returns whether the site's analytics are publicly accessible.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  isPublic: {
    description: &#x22;Whether the site's analytics are publicly accessible&#x22;,
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/is-public" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/is-public',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/is-public',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/is-public');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/is-public')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/is-public", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/is-public")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/is-public"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/is-public");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "isPublic": false
    }
    ```
  </div>
</div>


# Update Site Config (/de/docs/api/sites/update-config)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:siteId/config
    ```

    Updates site configuration settings. All fields are optional - only include the fields you want to update. Requires admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  domain: {
    description: 'Site domain',
    type: 'string',
    typeDescription: 'Valid domain format (e.g., example.com)',
    required: false,
  },
  public: {
    description: 'Make analytics publicly accessible',
    type: 'boolean',
    required: false,
  },
  saltUserIds: {
    description: 'Salt user IDs for privacy',
    type: 'boolean',
    required: false,
  },
  blockBots: {
    description: 'Block bot traffic',
    type: 'boolean',
    required: false,
  },
  excludedIPs: {
    description: 'List of IP addresses or CIDR ranges to exclude',
    type: 'string[]',
    typeDescription: 'Max 100 entries',
    required: false,
  },
  excludedCountries: {
    description: 'List of country codes to exclude',
    type: 'string[]',
    typeDescription: '2-letter ISO codes (e.g., US, GB)',
    required: false,
  },
  sessionReplay: {
    description: 'Enable session replay',
    type: 'boolean',
    required: false,
  },
  webVitals: {
    description: 'Enable Web Vitals tracking',
    type: 'boolean',
    required: false,
  },
  trackErrors: {
    description: 'Enable error tracking',
    type: 'boolean',
    required: false,
  },
  trackOutbound: {
    description: 'Enable outbound link tracking',
    type: 'boolean',
    required: false,
  },
  trackUrlParams: {
    description: 'Enable URL parameter tracking',
    type: 'boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the update was successful',
    type: 'boolean',
  },
  message: {
    description: 'Status message',
    type: 'string',
  },
  config: {
    description: 'Updated site configuration',
    type: 'object',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/sites/123/config" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"public": true, "blockBots": true, "excludedCountries": ["CN", "RU"]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/config',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              public: true,
              blockBots: true,
              excludedCountries: ['CN', 'RU']
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/sites/123/config',
            json={
                'public': True,
                'blockBots': True,
                'excludedCountries': ['CN', 'RU']
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/config');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'public' => true,
            'blockBots' => true,
            'excludedCountries' => ['CN', 'RU']
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/config')
        req = Net::HTTP::Put.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = { public: true, blockBots: true, excludedCountries: ['CN', 'RU'] }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{"public": true, "blockBots": true, "excludedCountries": ["CN", "RU"]}`))
        req, _ := http.NewRequest("PUT", "https://app.rybbit.io/api/sites/123/config", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .put("https://app.rybbit.io/api/sites/123/config")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "public": true,
                "blockBots": true,
                "excludedCountries": ["CN", "RU"]
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"public\": true, \"blockBots\": true, \"excludedCountries\": [\"CN\", \"RU\"]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/config"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"public\": true, \"blockBots\": true, \"excludedCountries\": [\"CN\", \"RU\"]}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PutAsync("https://app.rybbit.io/api/sites/123/config", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "message": "Site configuration updated successfully",
      "config": {
        "public": true,
        "saltUserIds": false,
        "blockBots": true,
        "excludedIPs": [],
        "excludedCountries": ["CN", "RU"],
        "sessionReplay": true,
        "webVitals": true,
        "trackErrors": true,
        "trackOutbound": true,
        "trackUrlParams": false
      }
    }
    ```
  </div>
</div>


# Update Private Link Config (/de/docs/api/sites/update-private-link)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:siteId/private-link-config
    ```

    Generates or revokes a private link key for sharing analytics without authentication. Requires admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  action: {
    description: 'Action to perform',
    type: 'string',
    typeDescription: '&#x22;generate_private_link_key&#x22; | &#x22;revoke_private_link_key&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  data: {
    description: 'Updated private link configuration',
    type: 'object',
  },
}"
    />

    #### Data Object [#data-object]

    <TypeTable
      type="{
  privateLinkKey: {
    description: 'New private link key (for generate), or null (for revoke)',
    type: 'string | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/123/private-link-config" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"action": "generate_private_link_key"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/private-link-config',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              action: 'generate_private_link_key'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/123/private-link-config',
            json={
                'action': 'generate_private_link_key'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/private-link-config');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'action' => 'generate_private_link_key'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/private-link-config')
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = { action: 'generate_private_link_key' }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{"action": "generate_private_link_key"}`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/123/private-link-config", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/123/private-link-config")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "action": "generate_private_link_key"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"action\": \"generate_private_link_key\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/private-link-config"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"action\": \"generate_private_link_key\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/123/private-link-config", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": {
        "privateLinkKey": "f6e5d4c3b2a1"
      }
    }
    ```
  </div>
</div>


# Get User Trait Keys (/de/docs/api/user-traits/keys)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/user-traits/keys
    ```

    Returns the known user trait keys with the number of users that have each.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  keys: {
    description: 'Array of user trait keys',
    type: 'TraitKey[]',
  },
}"
    />

    #### TraitKey Object [#traitkey-object]

    <TypeTable
      type="{
  key: {
    description: 'The trait name',
    type: 'string',
  },
  userCount: {
    description: 'Number of users that have this trait',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/user-traits/keys" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/user-traits/keys',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/user-traits/keys',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/user-traits/keys');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/user-traits/keys')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/user-traits/keys", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/user-traits/keys")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/user-traits/keys"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/user-traits/keys");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "keys": [
        { "key": "plan", "userCount": 1240 },
        { "key": "company", "userCount": 860 }
      ]
    }
    ```
  </div>
</div>


# Get Users by Trait (/de/docs/api/user-traits/users)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/user-traits/users
    ```

    Returns users matching a specific trait key and value, with location and session metadata.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  key: {
    description: 'The trait key to match on',
    type: 'string',
    required: true,
  },
  value: {
    description: 'The trait value to match on',
    type: 'string',
    required: true,
  },
  limit: {
    description: 'Maximum number of users to return',
    type: 'number',
    default: '50',
  },
  offset: {
    description: 'Number of users to skip',
    type: 'number',
    default: '0',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  users: {
    description: 'Array of matching users',
    type: 'TraitUser[]',
  },
  total: {
    description: 'Total number of matching users',
    type: 'number',
  },
  hasMore: {
    description: 'Whether more users are available beyond this page',
    type: 'boolean',
  },
}"
    />

    #### TraitUser Object [#traituser-object]

    <TypeTable
      type="{
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  traits: {
    description: &#x22;The user's full traits map&#x22;,
    type: 'object',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  sessions: {
    description: 'Total number of sessions',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/user-traits/users',
            params={
                'key': 'plan',
                'value': 'pro'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "users": [
        {
          "user_id": "a1b2c3",
          "identified_user_id": "user_987",
          "traits": { "plan": "pro", "company": "Acme" },
          "country": "US",
          "region": "California",
          "city": "CA-San Francisco",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "sessions": 14
        }
      ],
      "total": 1,
      "hasMore": false
    }
    ```
  </div>
</div>


# Get User Trait Values (/de/docs/api/user-traits/values)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/user-traits/values
    ```

    Returns the distinct values for a given trait key, with user counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  key: {
    description: 'The trait key to list values for',
    type: 'string',
    required: true,
  },
  limit: {
    description: 'Maximum number of values to return',
    type: 'number',
    default: '1000',
  },
  offset: {
    description: 'Number of values to skip',
    type: 'number',
    default: '0',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  values: {
    description: 'Array of distinct trait values',
    type: 'TraitValue[]',
  },
  total: {
    description: 'Total number of distinct values',
    type: 'number',
  },
  hasMore: {
    description: 'Whether more values are available beyond this page',
    type: 'boolean',
  },
}"
    />

    #### TraitValue Object [#traitvalue-object]

    <TypeTable
      type="{
  value: {
    description: 'The trait value',
    type: 'string',
  },
  userCount: {
    description: 'Number of users with this value',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/user-traits/values?key=plan" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/user-traits/values?key=plan',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/user-traits/values',
            params={
                'key': 'plan'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/user-traits/values?key=plan');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/user-traits/values?key=plan')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/user-traits/values?key=plan", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/user-traits/values?key=plan")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/user-traits/values?key=plan"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/user-traits/values?key=plan");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "values": [
        { "value": "pro", "userCount": 340 },
        { "value": "free", "userCount": 900 }
      ],
      "total": 2,
      "hasMore": false
    }
    ```
  </div>
</div>


# Get User Info (/de/docs/api/users/info)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/users/:userId
    ```

    Returns detailed information about a specific user, including their profile traits and linked devices.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  userId: {
    description: 'User ID (device fingerprint or identified user ID)',
    type: 'string',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'User info object',
    type: 'UserInfo',
  },
}"
    />

    #### UserInfo Object [#userinfo-object]

    <TypeTable
      type="{
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  traits: {
    description: 'Custom user traits/properties set via identify()',
    type: 'object | null',
  },
  sessions: {
    description: 'Total number of sessions',
    type: 'number',
  },
  pageviews: {
    description: 'Total pageviews',
    type: 'number',
  },
  events: {
    description: 'Total custom events',
    type: 'number',
  },
  duration: {
    description: 'Average session duration in seconds',
    type: 'number',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  language: {
    description: 'Browser language',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
  first_seen: {
    description: 'First activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  last_seen: {
    description: 'Most recent activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  timezone: {
    description: 'Timezone reported by the browser',
    type: 'string',
  },
  ip: {
    description: 'Last known IP address',
    type: 'string',
  },
  first_referrer: {
    description: 'Referrer URL of the first session',
    type: 'string',
  },
  first_channel: {
    description: 'Acquisition channel of the first session',
    type: 'string',
  },
  first_entry_page: {
    description: 'Entry page path of the first session',
    type: 'string',
  },
  first_utm_source: {
    description: 'UTM source of the first session',
    type: 'string',
  },
  first_utm_medium: {
    description: 'UTM medium of the first session',
    type: 'string',
  },
  first_utm_campaign: {
    description: 'UTM campaign of the first session',
    type: 'string',
  },
  last_referrer: {
    description: 'Referrer URL of the most recent session',
    type: 'string',
  },
  last_channel: {
    description: 'Acquisition channel of the most recent session',
    type: 'string',
  },
  vitals: {
    description: 'p75 Core Web Vitals for this user, or null when no performance data exists',
    type: 'UserVitals | null',
  },
  locations: {
    description: 'Per-location breakdown of sessions',
    type: 'UserLocation[]',
  },
  devices: {
    description: 'Per-device breakdown of sessions',
    type: 'UserDevice[]',
  },
  linked_devices: {
    description: 'Devices linked to this identified user',
    type: 'LinkedDevice[]',
  },
}"
    />

    #### UserVitals Object [#uservitals-object]

    <TypeTable
      type="{
  lcp_p75: {
    description: 'p75 Largest Contentful Paint (ms)',
    type: 'number | null',
  },
  cls_p75: {
    description: 'p75 Cumulative Layout Shift',
    type: 'number | null',
  },
  inp_p75: {
    description: 'p75 Interaction to Next Paint (ms)',
    type: 'number | null',
  },
  fcp_p75: {
    description: 'p75 First Contentful Paint (ms)',
    type: 'number | null',
  },
  ttfb_p75: {
    description: 'p75 Time to First Byte (ms)',
    type: 'number | null',
  },
  performance_events: {
    description: 'Number of performance events collected',
    type: 'number',
  },
}"
    />

    #### UserLocation Object [#userlocation-object]

    <TypeTable
      type="{
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  sessions: {
    description: 'Number of sessions from this location',
    type: 'number',
  },
  last_seen: {
    description: 'Most recent activity from this location',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />

    #### UserDevice Object [#userdevice-object]

    <TypeTable
      type="{
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
  sessions: {
    description: 'Number of sessions on this device',
    type: 'number',
  },
  last_seen: {
    description: 'Most recent activity on this device',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />

    #### LinkedDevice Object [#linkeddevice-object]

    <TypeTable
      type="{
  anonymous_id: {
    description: 'Anonymous device fingerprint',
    type: 'string',
  },
  created_at: {
    description: 'When the device was linked',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/users/user@example.com" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/users/user@example.com',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/users/user@example.com',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/users/user@example.com');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/users/user@example.com')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/users/user@example.com", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/users/user@example.com")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/users/user@example.com"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/users/user@example.com");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "user_id": "abc123def456",
        "identified_user_id": "user@example.com",
        "traits": {
          "name": "John Doe",
          "plan": "pro",
          "company": "Acme Inc"
        },
        "sessions": 12,
        "pageviews": 156,
        "events": 23,
        "duration": 245,
        "country": "US",
        "region": "California",
        "city": "San Francisco",
        "language": "en-US",
        "browser": "Chrome",
        "browser_version": "120.0.0",
        "operating_system": "macOS",
        "operating_system_version": "14.2",
        "device_type": "desktop",
        "screen_width": 2560,
        "screen_height": 1440,
        "first_seen": "2024-01-15T10:30:00.000Z",
        "last_seen": "2024-01-31T14:22:00.000Z",
        "timezone": "America/Los_Angeles",
        "ip": "203.0.113.42",
        "first_referrer": "https://google.com",
        "first_channel": "Organic Search",
        "first_entry_page": "/pricing",
        "first_utm_source": "google",
        "first_utm_medium": "cpc",
        "first_utm_campaign": "launch",
        "last_referrer": "https://twitter.com",
        "last_channel": "Social",
        "vitals": {
          "lcp_p75": 1240,
          "cls_p75": 0.02,
          "inp_p75": 180,
          "fcp_p75": 890,
          "ttfb_p75": 210,
          "performance_events": 48
        },
        "locations": [
          {
            "country": "US",
            "region": "California",
            "city": "San Francisco",
            "sessions": 10,
            "last_seen": "2024-01-31T14:22:00.000Z"
          }
        ],
        "devices": [
          {
            "device_type": "desktop",
            "browser": "Chrome",
            "browser_version": "120.0.0",
            "operating_system": "macOS",
            "operating_system_version": "14.2",
            "screen_width": 2560,
            "screen_height": 1440,
            "sessions": 9,
            "last_seen": "2024-01-31T14:22:00.000Z"
          }
        ],
        "linked_devices": [
          {
            "anonymous_id": "xyz789ghi012",
            "created_at": "2024-01-20T08:15:00.000Z"
          }
        ]
      }
    }
    ```
  </div>
</div>


# Get Users (/de/docs/api/users/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/users
    ```

    Returns a paginated list of users with their analytics data. Supports filtering by identified users only.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  page_size: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  sort_by: {
    description: 'Field to sort by',
    type: 'string',
    typeDescription: '&#x22;first_seen&#x22; | &#x22;last_seen&#x22; | &#x22;pageviews&#x22; | &#x22;sessions&#x22; | &#x22;events&#x22;',
    default: 'last_seen',
  },
  sort_order: {
    description: 'Sort direction',
    type: 'string',
    typeDescription: '&#x22;asc&#x22; | &#x22;desc&#x22;',
    default: 'desc',
  },
  identified_only: {
    description: 'Only return users with a custom identified_user_id',
    type: 'string',
    typeDescription: '&#x22;true&#x22; | &#x22;false&#x22;',
    default: 'false',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of user objects',
    type: 'User[]',
  },
  totalCount: {
    description: 'Total number of users across all pages',
    type: 'number',
  },
  page: {
    description: 'Current page number',
    type: 'number',
  },
  pageSize: {
    description: 'Number of results per page',
    type: 'number',
  },
}"
    />

    #### User Object [#user-object]

    <TypeTable
      type="{
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified, empty string otherwise',
    type: 'string',
  },
  traits: {
    description: 'Custom user traits/properties',
    type: 'object | null',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  language: {
    description: 'Browser language',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  device_type: {
    description: 'Device type (desktop, mobile, tablet)',
    type: 'string',
  },
  pageviews: {
    description: 'Total pageviews by this user',
    type: 'number',
  },
  events: {
    description: 'Total custom events by this user',
    type: 'number',
  },
  sessions: {
    description: 'Total sessions by this user',
    type: 'number',
  },
  hostname: {
    description: 'First hostname visited',
    type: 'string',
  },
  first_seen: {
    description: 'First activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  last_seen: {
    description: 'Most recent activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/users',
            params={
                'page': 1,
                'page_size': 10,
                'sort_by': 'last_seen',
                'sort_order': 'desc'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "user_id": "abc123def456",
          "identified_user_id": "user@example.com",
          "traits": {
            "plan": "pro",
            "company": "Acme Inc"
          },
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "language": "en-US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "pageviews": 156,
          "events": 23,
          "sessions": 12,
          "hostname": "example.com",
          "first_seen": "2024-01-15T10:30:00.000Z",
          "last_seen": "2024-01-31T14:22:00.000Z"
        }
      ],
      "totalCount": 1247,
      "page": 1,
      "pageSize": 10
    }
    ```
  </div>
</div>


# Get User Session Count (/de/docs/api/users/session-count)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/users/session-count
    ```

    Returns the number of sessions per day for a specific user. Useful for visualizing user engagement over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  user_id: {
    description: 'User ID (device fingerprint or identified user ID)',
    type: 'string',
    required: true,
  },
  time_zone: {
    description: 'Timezone for date grouping',
    type: 'string',
    default: 'UTC',
    typeDescription: 'IANA timezone (e.g., &#x22;America/New_York&#x22;)',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of daily session counts',
    type: 'DailyCount[]',
  },
}"
    />

    #### DailyCount Object [#dailycount-object]

    <TypeTable
      type="{
  date: {
    description: 'Date',
    type: 'string',
    typeDescription: 'YYYY-MM-DD format',
  },
  sessions: {
    description: 'Number of sessions on this date',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/users/session-count',
            params={
                'user_id': 'abc123def456',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "date": "2024-01-15",
          "sessions": 2
        },
        {
          "date": "2024-01-18",
          "sessions": 1
        },
        {
          "date": "2024-01-22",
          "sessions": 3
        },
        {
          "date": "2024-01-31",
          "sessions": 1
        }
      ]
    }
    ```
  </div>
</div>


# Gatsby (/de/docs/guides/react/gatsby)





Gatsby generates the `<head>` of every page at build time. Add the snippet through the `onRenderBody` API in `gatsby-ssr.js`, or with Gatsby's own `<Script>` component if you want control over load timing.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Gatsby [#add-the-snippet-to-gatsby]

    <Tabs items="[&#x22;gatsby-ssr.js&#x22;, &#x22;Gatsby Script component&#x22;]">
      <Tab value="gatsby-ssr.js">
        Create `gatsby-ssr.js` at the root of your project if it does not exist and register the script with `setHeadComponents`:

        ```javascript title="gatsby-ssr.js"
        import React from "react";

        export const onRenderBody = ({ setHeadComponents }) => {
          setHeadComponents([
            <script
              key="rybbit-analytics"
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              defer
            />,
          ]);
        };
        ```

        This puts the tag in the `<head>` of every generated page.
      </Tab>

      <Tab value="Gatsby Script component">
        The [Gatsby Script API](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-script/) loads third-party scripts with a chosen `strategy` (`post-hydrate`, `idle` or `off-main-thread`). Render it in a layout component that wraps every page:

        ```jsx title="src/components/layout.js"
        import React from "react";
        import { Script } from "gatsby";

        export default function Layout({ children }) {
          return (
            <>
              {children}
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="post-hydrate"
              />
            </>
          );
        }
        ```
      </Tab>
    </Tabs>

    Rebuild the site (`gatsby build`) and deploy the `public` folder. Client-side navigation through Gatsby's `<Link>` is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any React component. Guard the call, because Gatsby renders components on the server during the build.

```jsx title="src/components/TrackedButton.js"
import React from "react";

export default function TrackedButton({ label, eventName, eventData }) {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event(eventName, eventData);
    }
  };

  return <button onClick={handleClick}>{label}</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after client-side navigation**: this is rare. If it happens, export `onRouteUpdate` from `gatsby-browser.js` and call `window.rybbit.pageview()` there when `location.pathname` changes. Test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Next.js (/de/docs/guides/react/next-js)





Next.js ships a [Script component](https://nextjs.org/docs/app/building-your-application/optimizing/scripts) that controls when a third-party script loads. Render it once in your root layout (App Router) or custom `App` (Pages Router) so the snippet is on every page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Next.js [#add-the-snippet-to-nextjs]

    Use `next/script` with `strategy="afterInteractive"` instead of a plain `<script>` tag. The `defer` attribute from the snippet is not needed; the strategy handles load timing.

    <Tabs items="[&#x22;App Router&#x22;, &#x22;Pages Router&#x22;]">
      <Tab value="App Router">
        ```jsx title="app/layout.js"
        import Script from "next/script";

        export default function RootLayout({ children }) {
          return (
            <html lang="en">
              <body>
                {children}
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```
      </Tab>

      <Tab value="Pages Router">
        ```jsx title="pages/_app.js"
        import Script from "next/script";

        export default function MyApp({ Component, pageProps }) {
          return (
            <>
              <Component {...pageProps} />
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </>
          );
        }
        ```
      </Tab>
    </Tabs>

    Client-side navigation through `<Link>` and `router.push()` is tracked automatically as pageviews; no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any client component. Guard the call, because the script loads after hydration and components can also render on the server.

```jsx title="components/MyButton.js"
"use client";

export default function MyButton({ title }) {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("button_click", { buttonTitle: title });
    }
  };

  return <button onClick={handleClick}>{title}</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Proxying through your own domain**: Next.js [rewrites](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites) can serve the script and its API from your domain. Follow the [Next.js proxy guide](/docs/proxy-guide/next-js); every endpoint must be rewritten, including `site/tracking-config`, otherwise the script silently falls back to default settings and features such as web vitals and session replay stay off.
* **Pageviews missing after client-side navigation**: this is rare; call `window.rybbit.pageview()` yourself after the route change only if the default behaviour does not work for you.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# React Router (/de/docs/guides/react/react-router)





In React Router framework mode (v7 and later, the successor to Remix), `app/root.tsx` renders the `<html>` document for every route. Add the snippet to the `<head>` in its `Layout` export. This guide supersedes the [Remix guide](/docs/guides/react/remix); if you use React Router only as a library inside a Vite app, follow the [React (Vite / CRA) guide](/docs/guides/react/vite-cra) instead.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to React Router [#add-the-snippet-to-react-router]

    Open `app/root.tsx` and add the tag inside `<head>` of the `Layout` component, after `<Meta />` and `<Links />`. `Layout` wraps the app, `HydrateFallback` and `ErrorBoundary`, so the snippet stays in place in every state:

    ```tsx title="app/root.tsx"
    import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";

    export function Layout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <Meta />
            <Links />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            {children}
            <ScrollRestoration />
            <Scripts />
          </body>
        </html>
      );
    }

    export default function App() {
      return <Outlet />;
    }
    ```

    If your `root.tsx` has no `Layout` export, add the tag to the `<head>` of the default `App` component instead. Restart the dev server after the change. Client-side navigation through `<Link>` and `useNavigate()` is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any route or component. Check for `window` first, because route modules also render on the server.

```tsx title="app/routes/pricing.tsx"
export default function Pricing() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("plan_selected", { plan: "pro" });
    }
  };

  return <button onClick={handleClick}>Choose Pro</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Nonce-based Content Security Policy**: if you pass a `nonce` to `<Scripts />` and `<ScrollRestoration />`, add the same `nonce` attribute to the Rybbit tag, otherwise the browser blocks it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Remix (/de/docs/guides/react/remix)





Remix renders the whole HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file and reaches every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Remix [#add-the-snippet-to-remix]

    Open `app/root.tsx` (or `app/root.jsx`) and add the tag inside `<head>`, after `<Meta />` and `<Links />`:

    ```tsx title="app/root.tsx"
    import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "@remix-run/react";

    export default function App() {
      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <Meta />
            <Links />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            <Outlet />
            <ScrollRestoration />
            <Scripts />
          </body>
        </html>
      );
    }
    ```

    Restart the dev server after the change. Client-side navigation after the initial server render is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any route or component. Check for `window` first, because Remix renders components on the server.

```tsx title="app/routes/offer.tsx"
export default function OfferRoute() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("offer_claimed", { feature: "Special Offer" });
    }
  };

  return <button onClick={handleClick}>Claim Offer</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after client-side navigation**: this is rare. If it happens, call `window.rybbit.pageview()` from a root-level effect that runs on `useLocation()` changes; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# TanStack Start (/de/docs/guides/react/tanstack-start)





TanStack Start manages the document head through the root route's `head()` option, rendered by `<HeadContent />` in `src/routes/__root.tsx`. Add the snippet to the `scripts` array returned by `head()` and it is on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to TanStack Start [#add-the-snippet-to-tanstack-start]

    Open `src/routes/__root.tsx` and add a `scripts` entry to the object returned by `head()`. `<HeadContent />` in the root document renders it as a `<script>` tag inside `<head>`:

    ```tsx title="src/routes/__root.tsx"
    import type { ReactNode } from "react";
    import { Outlet, createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";

    export const Route = createRootRoute({
      head: () => ({
        meta: [
          { charSet: "utf-8" },
          { name: "viewport", content: "width=device-width, initial-scale=1" },
          { title: "My App" },
        ],
        scripts: [
          {
            src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
            defer: true,
          },
        ],
      }),
      component: RootComponent,
    });

    function RootComponent() {
      return (
        <RootDocument>
          <Outlet />
        </RootDocument>
      );
    }

    function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
      return (
        <html>
          <head>
            <HeadContent />
          </head>
          <body>
            {children}
            <Scripts />
          </body>
        </html>
      );
    }
    ```

    Use the `scripts` key inside `head()`, not the route-level `scripts` option: that one renders body scripts through `<Scripts />`, which also works but loads later. Client-side navigation through `<Link>` and `useNavigate()` is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any route component. Check for `window` first, because TanStack Start renders routes on the server by default.

```tsx title="src/routes/pricing.tsx"
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/pricing")({
  component: Pricing,
});

function Pricing() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("plan_selected", { plan: "pro" });
    }
  };

  return <button onClick={handleClick}>Choose Pro</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# React (Vite / CRA) (/de/docs/guides/react/vite-cra)





A client-side React app built with Vite or Create React App has a single HTML entry file. Paste the snippet into its `<head>` and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to React [#add-the-snippet-to-react]

    Find the HTML entry file for your tooling:

    * **Vite**: `index.html` at the project root.
    * **Create React App**: `public/index.html`.

    Paste the snippet just before `</head>`:

    ```html title="index.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <title>My React App</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="root"></div>
      </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Route changes made by React Router and similar libraries are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw.

```jsx title="src/components/LearnMoreButton.jsx"
export default function LearnMoreButton() {
  const handleClick = () => {
    if (window.rybbit) {
      window.rybbit.event("button_click", { category: "CTA", label: "Learn More" });
    }
  };

  return <button onClick={handleClick}>Learn More</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: this is rare with React Router. If it happens, call `window.rybbit.pageview()` after each route change; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# SvelteKit (/de/docs/guides/svelte/sveltekit)





SvelteKit renders every page through a single HTML shell at `src/app.html`, so adding the snippet there loads Rybbit on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to SvelteKit [#add-the-snippet-to-sveltekit]

    Open `src/app.html` and paste the snippet inside `<head>`, next to `%sveltekit.head%`:

    ```html title="src/app.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <link rel="icon" href="%sveltekit.assets%/favicon.png" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        %sveltekit.head%
      </head>
      <body data-sveltekit-preload-data="hover">
        <div style="display: contents">%sveltekit.body%</div>
      </body>
    </html>
    ```

    Rybbit tracks SvelteKit's client-side navigations as pageviews automatically; no router hook is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any Svelte component. Guard the call with `typeof window !== "undefined"`, since SvelteKit components also run on the server:

```svelte title="src/lib/components/ActionButton.svelte"
<script>
  function handleAction() {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("user_action", { component: "ActionButton" });
    }
  }
</script>

<button on:click={handleAction}>Perform action</button>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: automatic route tracking covers SvelteKit's router, so test the default first. If a navigation is still not recorded, trigger it from `afterNavigate` in your root layout:

  ```svelte title="src/routes/+layout.svelte"
  <script>
    import { afterNavigate } from "$app/navigation";

    afterNavigate(() => {
      if (typeof window !== "undefined" && window.rybbit) {
        window.rybbit.pageview();
      }
    });
  </script>
  ```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Svelte (Vite / Client-Side) (/de/docs/guides/svelte/vite)





A client-side Svelte app built with Vite (`npm create vite@latest -- --template svelte`) serves a single `index.html` at the project root. Add the snippet there and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Svelte [#add-the-snippet-to-svelte]

    Open `index.html` at the root of your project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Svelte App</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/main.js"></script>
      </body>
    </html>
    ```

    Placing it just before `</body>` also works, but `<head>` lets the script start loading sooner.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any Svelte component:

```svelte title="src/lib/ActionButton.svelte"
<script>
  function handleAction() {
    if (window.rybbit) {
      window.rybbit.event("user_action", { component: "ActionButton" });
    }
  }
</script>

<button on:click={handleAction}>Perform action</button>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: Rybbit tracks History API and hash navigations, which covers routers such as `svelte-routing` and `svelte-spa-router`. If a route change is still not recorded, call `window.rybbit.pageview()` from that router's navigation callback.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Nuxt.js (/de/docs/guides/vue/nuxt)





Nuxt has two ways to load Rybbit: the [Nuxt Scripts](https://scripts.nuxt.com/scripts/rybbit-analytics) module, which ships a first-class Rybbit registry entry with a typed composable, or the `app.head.script` array in `nuxt.config.ts`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Nuxt [#add-the-snippet-to-nuxt]

    <Tabs items="[&#x22;Nuxt Scripts (Nuxt 3 and 4)&#x22;, &#x22;nuxt.config head&#x22;]">
      <Tab value="Nuxt Scripts (Nuxt 3 and 4)">
        Install the module. This adds `@nuxt/scripts` to the `modules` array in your `nuxt.config`:

        ```bash
        npx nuxi module add scripts
        ```

        Register Rybbit under `scripts.registry` with the site ID from your snippet:

        ```typescript title="nuxt.config.ts"
        export default defineNuxtConfig({
          modules: ["@nuxt/scripts"],
          scripts: {
            registry: {
              rybbitAnalytics: {
                siteId: "YOUR_SITE_ID",
                trigger: "onNuxtReady",
              },
            },
          },
        });
        ```

        Options:

        * `siteId` (required): your Rybbit site ID.
        * `autoTrackPageview`: track pageviews automatically (on by default).
        * `trackSpa`: track client-side route changes (on by default).
        * `analyticsHost`: script and API host for a self-hosted instance, for example `https://your-instance.com/api`.
        * `sessionReplay`, `webVitals`, `trackOutbound`: optional features.

        <Callout type="info">
          To keep the site ID out of source control, leave `siteId` unset and provide `NUXT_PUBLIC_SCRIPTS_RYBBIT_ANALYTICS_SITE_ID` in the environment; Nuxt Scripts reads it at runtime.
        </Callout>
      </Tab>

      <Tab value="nuxt.config head">
        Add the script to the `app.head.script` array in `nuxt.config.ts`:

        ```typescript title="nuxt.config.ts"
        export default defineNuxtConfig({
          app: {
            head: {
              script: [
                {
                  src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                  defer: true,
                },
              ],
            },
          },
        });
        ```

        On Nuxt 2 the array is `head.script` at the top level of `nuxt.config.js`, with the same entry.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

With Nuxt Scripts, use the `useScriptRybbitAnalytics` composable. Its `proxy` queues calls until the script is ready, so it is safe to call immediately:

```vue title="components/ActionButton.vue"
<template>
  <button @click="handleAction">Track action</button>
</template>

<script setup>
const { proxy } = useScriptRybbitAnalytics();

function handleAction() {
  proxy.event("nuxt_interaction", { detail: "User clicked the action button" });
}
</script>
```

With the `app.head.script` method, call `window.rybbit` directly and guard it with `import.meta.client`, since components also run on the server (on Nuxt 2 use `process.client`):

```vue title="components/ActionButton.vue"
<template>
  <button @click="handleAction">Track action</button>
</template>

<script setup>
function handleAction() {
  if (import.meta.client && window.rybbit) {
    window.rybbit.event("nuxt_interaction", { detail: "User clicked the action button" });
  }
}
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: both methods track Nuxt's client-side route changes automatically, so test the default first. If a route change is still not recorded, call `window.rybbit.pageview()` from a `router.afterEach` hook in a client plugin.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Vue.js (Vite / Client-Side) (/de/docs/guides/vue/vite)





A client-side Vue app built with Vite (`npm create vue@latest` or `npm create vite@latest -- --template vue`) serves a single `index.html` at the project root. Add the snippet there and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Vue.js [#add-the-snippet-to-vuejs]

    Open `index.html` at the root of your project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" href="/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Vue App</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/main.js"></script>
      </body>
    </html>
    ```

    Placing it just before `</body>` also works, but `<head>` lets the script start loading sooner.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component or method:

```vue title="src/components/ActionButton.vue"
<template>
  <button @click="trackAction">Track action</button>
</template>

<script setup>
function trackAction() {
  if (window.rybbit) {
    window.rybbit.event("custom_vue_action", { detail: "User performed an action" });
  }
}
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: Rybbit tracks Vue Router navigations automatically, so test the default first. If a route change is still not recorded, trigger it from an `afterEach` guard in your router setup:

  ```javascript title="src/router/index.js"
  import { createRouter, createWebHistory } from "vue-router";

  const router = createRouter({
    history: createWebHistory(import.meta.env.BASE_URL),
    routes: [/* your routes */],
  });

  router.afterEach(() => {
    if (window.rybbit) {
      window.rybbit.pageview();
    }
  });

  export default router;
  ```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Account settings (/fr/docs/account-settings)







Access your account settings by clicking on "Account" or going to [app.rybbit.io/settings/account](https://app.rybbit.io/settings/account).

<img alt="account settings" src="__img0" />

## Account [#account]

### Name [#name]

Update your display name shown across the platform. This name is visible to other members in your organization.

### Email [#email]

Update your email address for account notifications and login. This is the primary email associated with your account.

### Weekly Email Reports <span className="text-green-500 text-sm">(Cloud)</span> [#weekly-email-reports-cloud]

Enable or disable automatic weekly email reports. When enabled, you'll receive a summary of your analytics performance delivered to your inbox each week.

### Sign Out [#sign-out]

Sign out of your current session.

## Security [#security]

### Change Password [#change-password]

Update your password to keep your account secure.

### Delete Account [#delete-account]

Permanently delete your account and all associated data.

<Callout type="warn">
  This action cannot be undone. If you have an active subscription, you must cancel it before deleting your account.
</Callout>

## API Keys [#api-keys]

Generate API keys to access Rybbit's analytics endpoints from your applications.

### Creating an API Key [#creating-an-api-key]

1. Enter a name for your API key (e.g., "Production App", "Development")
2. Optionally enable **Restrict permissions** to limit the key to specific resources. Leave it off for a full-access key that can do everything you can.
3. Click "Create"
4. Copy and save the generated key immediately

<Callout type="warn">
  On Rybbit Cloud, API keys require a Standard or Pro plan. On a free plan you'll see an upgrade prompt in place of the creation form.
</Callout>

<Callout type="warn">
  API keys are only shown once when created. Store your key securely as you won't be able to view it again.
</Callout>

### Managing API Keys [#managing-api-keys]

Your existing API keys are displayed in a table showing:

* **Name** - The name you assigned to the key
* **Key** - A preview of the key (first few characters)
* **Permissions** - Whether the key has full access or is restricted to specific scopes
* **Created** - When the key was created
* **Last used** - When the key last made a request

You can delete API keys that are no longer needed. Deleting a key immediately revokes access for any applications using it.

### Using API Keys [#using-api-keys]

Include your API key in requests to Rybbit's API endpoints. See the [API documentation](/docs/api) for available endpoints and usage examples.


# Autocapture (/fr/docs/autocapture)



Rybbit can automatically capture common user interactions without requiring any code changes. These features can be enabled in your [Site Settings](/docs/site-settings) under the "Auto Capture" section.

## Available Autocapture Features [#available-autocapture-features]

| Feature           | Description                              | Event Type                    |
| ----------------- | ---------------------------------------- | ----------------------------- |
| Outbound Links    | Track clicks on external links           | `outbound`                    |
| Error Tracking    | Capture JavaScript errors and exceptions | `error`                       |
| Button Clicks     | Track clicks on buttons                  | `button_click`                |
| Copy Events       | Track when users copy text               | `copy`                        |
| Form Interactions | Track form submissions and input changes | `form_submit`, `input_change` |

## Outbound Links [#outbound-links]

When enabled, Rybbit automatically tracks clicks on links that navigate to external domains.

**Tracked properties:**

* `url` - The destination URL
* `text` - The link text
* `target` - The link target attribute (e.g., `_blank`, `_self`)

## Error Tracking [#error-tracking]

Captures uncaught JavaScript errors and unhandled promise rejections from your site. Only errors originating from your domain are tracked (third-party script errors are filtered out).

**Tracked properties:**

* `message` - The error message
* `stack` - Stack trace (truncated to 2000 characters)
* `fileName` - Source file where the error occurred
* `lineNumber` - Line number
* `columnNumber` - Column number

## Button Clicks [#button-clicks]

Automatically tracks clicks on:

* `<button>` elements
* Elements with `role="button"`
* `<input type="submit">` and `<input type="button">`

**Tracked properties:**

* `text` - The button's text content (falls back to `aria-label`, then `value` for input buttons, then `title`)

### Adding Custom Properties [#adding-custom-properties]

You can add custom properties to auto-tracked button clicks using `data-rybbit-prop-*` attributes:

```html
<button
  data-rybbit-prop-category="pricing"
  data-rybbit-prop-variant="blue"
>
  Buy Now
</button>
```

This tracks: `{ text: "Buy Now", category: "pricing", variant: "blue" }`

### Skipping Autocapture for Specific Buttons [#skipping-autocapture-for-specific-buttons]

If you want to track a button with a custom event instead of the automatic `button_click`, add the `data-rybbit-event` attribute:

```html
<!-- This button will fire a custom "signup" event, NOT a button_click -->
<button data-rybbit-event="signup" data-rybbit-prop-plan="pro">
  Sign Up
</button>
```

See [Track Events](/docs/track-events) for more details on custom event tracking.

## Copy Events [#copy-events]

Tracks when users copy text from your site using Ctrl+C, Cmd+C, or the context menu.

**Tracked properties:**

* `text` - The copied text (truncated to 500 characters)
* `textLength` - Original length of the copied text (only included if text was truncated)
* `sourceElement` - The HTML tag where the text was copied from (e.g., `p`, `div`, `span`)

## Form Interactions [#form-interactions]

Tracks two types of form events:

### Form Submissions (`form_submit`) [#form-submissions-form_submit]

Triggered when a form is submitted.

**Tracked properties:**

* `formId` - The form's `id` attribute
* `formName` - The form's `name` attribute
* `formAction` - The form's `action` URL
* `method` - HTTP method (GET, POST, etc.)
* `fieldCount` - Number of form fields
* `ariaLabel` - The form's `aria-label` attribute (if present)

You can add custom properties using `data-rybbit-prop-*` on the form element:

```html
<form
  id="signup"
  data-rybbit-prop-form-type="registration"
  data-rybbit-prop-variant="a"
>
  ...
</form>
```

### Input Changes (`input_change`) [#input-changes-input_change]

Triggered when a user changes the value of an input, select, or textarea field. Disabled inputs are automatically excluded from tracking.

**Tracked properties:**

* `element` - The element type (`input`, `select`, or `textarea`)
* `inputType` - For inputs: the type attribute (e.g., `text`, `email`, `checkbox`)
* `inputName` - The field's `name`, `id`, `aria-label`, or `placeholder` attribute (first available)
* `formId` - The parent form's `id` (if within a form)
* `formName` - The parent form's `name` (if within a form)

You can add custom properties using `data-rybbit-prop-*` on the input element:

```html
<input
  name="email"
  data-rybbit-prop-field-category="contact"
/>

<select
  name="country"
  data-rybbit-prop-section="demographics"
>
  ...
</select>
```

**Privacy note:** Hidden inputs, password fields, and disabled inputs are automatically excluded from tracking.

## Enabling Autocapture [#enabling-autocapture]

1. Go to your site's **Settings**
2. Navigate to the **Auto Capture** section
3. Toggle on the features you want to enable

Changes take effect immediately for new visitors. Existing sessions may need to refresh to pick up the new configuration.

***

**Related Documentation:**

* [Track Events](/docs/track-events) - Manual event tracking
* [Site Settings](/docs/site-settings) - Configure your site
* [Behavior Analytics - Events](/docs/behavior-analytics/events) - View captured events


# Billing (/fr/docs/billing-settings)





Access billing settings by hovering over the sidebar and clicking "Billing".

Subscriptions are scoped to a single organization. If you have multiple organizations, each one requires its own subscription. Switching organizations will show that organization's subscription status.


# Bot detection (/fr/docs/bot-detection)





Rybbit can filter bot traffic before it reaches your normal analytics. When **Block Bot Traffic** is enabled for a site, each incoming tracking request is checked by several detection layers. If any layer identifies the request as bot traffic, the request is excluded from the normal analytics tables and stored separately for bot traffic inspection.

## Enabling Bot Detection [#enabling-bot-detection]

Bot blocking is configured per site:

1. Open your site in the Rybbit dashboard
2. Go to **Site Settings**
3. Enable **Block Bot Traffic**

When this setting is off, Rybbit does not block requests based on bot detection.

## What Happens to Detected Bots [#what-happens-to-detected-bots]

Detected bot requests are not added to your normal analytics data. This keeps dashboard totals, reports, journeys, funnels, session lists, and usage metrics focused on human traffic.

Detected bot visits also do not count toward billable analytics usage. If bot blocking filters a request, you are not charged for that bot visit.

Rybbit still stores a compact bot event record so you can inspect what was filtered. Bot event records include route, device, location, ASN, and which detection layers matched.

## Detection Layers [#detection-layers]

Rybbit runs all detection layers before making a final decision. A request can match multiple layers, and the bot event records every layer that matched.

<Steps>
  <Step>
    ### User-Agent Patterns [#user-agent-patterns]

    The `ua_pattern` layer checks the request user-agent against known bot, crawler, AI agent, SEO tool, monitoring, social preview, framework, and headless browser patterns.

    Examples include:

    * Search engine crawlers
    * Headless browser user-agents
    * AI crawler and agent user-agents
    * SEO and monitoring tools
    * Script or framework HTTP clients
  </Step>

  <Step>
    ### Header Heuristics [#header-heuristics]

    The `header_heuristics` layer scores request headers for browser consistency.

    It looks for signals such as:

    * Missing browser headers
    * Suspicious fetch metadata
    * Inconsistent browser claims
    * Headless or automation-looking headers
    * Stale or unusual Chrome versions
    * Script/framework-style requests that do not look like normal browser traffic

    This layer is useful because many bots use a browser-like user-agent but do not send the full set of headers a real browser normally sends.
  </Step>

  <Step>
    ### Client Signals [#client-signals]

    The `client_signals` layer uses lightweight browser-side signals collected by the tracking script.

    Signals include:

    * Automation APIs
    * Zero or impossible window dimensions
    * Default automation viewport sizes such as `800x600` and `1024x768`
    * Suspicious outer window dimensions
    * Missing browser APIs
    * Missing Chrome globals
    * SwiftShader renderer signals
    * Empty plugin lists

    Rybbit combines these into a weighted score. Strong signals can identify bot traffic on their own, while weaker signals contribute supporting evidence.
  </Step>

  <Step>
    ### ASN and Network Signals [#asn-and-network-signals]

    The `bot_asn` layer uses ASN metadata from the resolved IP address.

    There are two kinds of ASN matches:

    * **Curated bot provider ASNs**: Known AI, scanner, and internet measurement providers can trigger bot detection directly.
    * **Generic hosting/datacenter ASNs**: Hosting ASNs are treated as supporting evidence. They are recorded when another bot layer also matches, but generic hosting ASN alone is not enough to block a request.

    This avoids filtering every legitimate visitor who happens to browse through a cloud, CDN, VPN, corporate gateway, or first-party proxy, while still preserving ASN context when other bot evidence exists.
  </Step>

  <Step>
    ### Rate and Anomaly Detection [#rate-and-anomaly-detection]

    The `rate_anomaly` layer watches for bursty or crawl-shaped behavior.

    It tracks short rolling windows for patterns such as:

    * Too many events from the same IP and user-agent
    * Too many events from the same IP
    * Too many distinct paths visited quickly
    * Too many different user-agents from one IP
    * Too many hostnames from one IP
    * High site-wide volume from one user-agent
    * Large volumes of requests missing client-side bot scores

    This layer is designed to catch fast crawlers, floods, and replayed tracking requests that may not have obvious user-agent or browser fingerprint signals.
  </Step>
</Steps>

## Bot Identity [#bot-identity]

Every detected bot carries the layers that caught it. Bots matched by one of Rybbit's curated user-agent patterns carry three more fields, which is what the Bots dashboard groups by:

| Field          | Example       | Meaning                                      |
| -------------- | ------------- | -------------------------------------------- |
| `bot_name`     | `GPTBot`      | The name the bot publishes in its user agent |
| `bot_operator` | `OpenAI`      | Who runs it                                  |
| `bot_purpose`  | `ai_training` | What the fetch is for                        |

A bot matched only by a broad pattern (`crawl`, `spider`) is still filtered, but has no published identity — those rows read as **Unnamed**, which is more useful than a guess.

### Purposes [#purposes]

`bot_purpose` answers a different question from `bot_category`. Category groups bots into families; purpose says what the operator does with the page, which is the distinction that matters for AI traffic:

| Purpose          | What it means                                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ai_training`    | Collecting pages to train a model. Sends no readers back. Examples: GPTBot, ClaudeBot, CCBot, Google-Extended, Bytespider                                       |
| `ai_search`      | Indexing pages so an assistant can cite them. Can send readers back. Examples: OAI-SearchBot, Claude-SearchBot, PerplexityBot                                   |
| `ai_agent`       | A person asked an assistant to open the page, and it fetched it there and then. Examples: ChatGPT-User, Claude-User, Perplexity-User, Google-Agent, Claude Code |
| `search`         | Classic search engine indexing                                                                                                                                  |
| `social_preview` | Link unfurling                                                                                                                                                  |
| `seo`            | Backlink, rank, and site-audit crawlers                                                                                                                         |
| `monitoring`     | Uptime, synthetic, and performance checks                                                                                                                       |
| `security`       | Scanners                                                                                                                                                        |
| `scripted`       | HTTP libraries and CLI clients                                                                                                                                  |
| `headless`       | Browser automation                                                                                                                                              |

Splitting the AI family in three is the point: a training crawler reading 4,000 pages and a person's assistant opening one page are both `category: ai`, but they mean opposite things for your site.

<Callout>
  These fields were added in a later release. Bot events recorded before then have empty identity fields and appear as **Unnamed** / **Unclassified**; nothing is backfilled.
</Callout>

## How Decisions Are Made [#how-decisions-are-made]

Rybbit does not stop at the first matching layer. It runs every layer, records all matches, and then makes one final decision.

A request is marked as bot traffic when at least one blocking layer matches. The resulting bot event includes boolean fields for each layer:

* User-agent pattern
* Header heuristics
* Client signals
* Bot ASN
* Rate anomaly

Because multiple layers can match the same request, per-layer bot counts can add up to more than the total number of bot requests.

## Server-Side Tracking [#server-side-tracking]

Requests sent to `/api/track` with `Authorization: Bearer <api key>` and a valid API key are treated as trusted server-side ingestion. Four of the five layers are skipped: the headers, the client signals, the network address, and the request rate all belong to your server, not to the visitor it is reporting, so scoring them would convict your own backend.

The user-agent layer still runs, on the `user_agent` you send. Nothing changes for ordinary backend events — a request reporting a real browser's user agent is tracked normally.

### Reporting crawlers that never run JavaScript [#reporting-crawlers-that-never-run-javascript]

Rybbit's tracker is JavaScript, so a crawler that fetches your HTML and executes nothing never reaches Rybbit at all. Most AI training crawlers work exactly that way, which is why the Bots dashboard carries a note about its own coverage.

If you want to see them, report them from the edge — middleware, a worker, or a reverse proxy — forwarding the real request's `user_agent`:

```json
{
  "site_id": "1",
  "hostname": "example.com",
  "pathname": "/pricing",
  "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.2; +https://openai.com/gptbot"
}
```

A forwarded crawler user agent is classified and lands in your bot events with full identity, rather than in your analytics as a phantom visitor.

<Callout type="warn">
  Do not expose API keys in browser JavaScript. API keys are only for server-side requests.
</Callout>

## Proxies and CDN Setups [#proxies-and-cdn-setups]

If you proxy Rybbit through Cloudflare Workers, AWS CloudFront, Nginx, Caddy, or another reverse proxy, forward the original visitor IP:

```txt
X-Forwarded-For: <visitor-ip>
X-Real-IP: <visitor-ip>
```

Also preserve the original `User-Agent`, `Referer`, and `Accept-Language` headers where possible.

If the proxy IP is sent instead of the visitor IP, traffic may be geolocated to the proxy location and may inherit the proxy provider's ASN.

See the [proxy troubleshooting guide](/docs/proxy-guide/troubleshooting) for examples.

## What Bot Detection Does Not Guarantee [#what-bot-detection-does-not-guarantee]

Bot detection improves analytics quality, but no bot filter is perfect.

Some sophisticated bots can look like normal browsers. Some legitimate users may browse through unusual network paths or constrained browser environments. Rybbit uses multiple layers to reduce both misses and false positives, but you should still interpret bot counts as an operational signal rather than an exact measurement of all automation on your site.


# Comparison (/fr/docs/comparison)





| Feature                           | Rybbit                                                             | GA4                                                                | Plausible                                                            | Cloudflare                                                         |
| --------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Open Source**                   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Self-Hosting**                  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />\* | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Cookieless & Privacy friendly** | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Advanced Maps**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Advanced Filters**              | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Limited</span>    | <span className="inline-flex items-center gap-1">Limited</span>      | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Web Vitals**                    | <span className="inline-flex items-center gap-1">Paid</span>       | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Session Details**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **User Profiles**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Session Replays**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Funnels**                       | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Paid</span>         | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **User Journeys**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Retention Analysis**            | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Goals & Events**                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Real-time Dashboard**           | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Custom Events (JSON)**          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Limited</span>      | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Error Tracking**                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Public Dashboards**             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Organizations**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Frog 🐸**                       | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |

\* Plausible's Community Edition has very limited features compared to their cloud version


# Data Import (/fr/docs/data-import)





The data import feature allows you to migrate your historical analytics data from other platforms to Rybbit. This preserves your analytics history when switching from competitors, giving you a complete view of your data without losing valuable insights.

## Supported Platforms [#supported-platforms]

Currently, Rybbit supports importing data from:

* Umami
* Simple Analytics
* Plausible

Additional platforms may be added in the future based on user demand.

<Callout type="info">
  Umami and Simple Analytics are imported from a CSV export, while Plausible is imported from its ZIP export. The Import dialog automatically expects the correct file type for the platform you select.
</Callout>

## Plan Requirements [#plan-requirements]

### Cloud Version [#cloud-version]

| Plan     | Access          | Historical Window   | Monthly Event Limit |
| -------- | --------------- | ------------------- | ------------------- |
| Free     | ❌ Not available | -                   | -                   |
| Standard | ✅ Available     | 36 months (3 years) | Plan limit applies  |
| Pro      | ✅ Available     | 60 months (5 years) | Plan limit applies  |

### Self-Hosted Version [#self-hosted-version]

Self-hosted installations have **unlimited** access to data imports with no restrictions on:

* Historical data window (import data from any date)
* Event quotas (no monthly limits)
* Concurrent imports (no limit on active imports)

## Import Limits [#import-limits]

### Historical Data Windows [#historical-data-windows]

The historical data window determines how far back you can import data:

* **Standard plans**: Import data from the past 36 months (3 years)
* **Pro plans**: Import data from the past 60 months (5 years)
* **Self-hosted**: Unlimited - import data from any date

Events outside your plan's historical window will be automatically skipped during import.

### Event Quotas [#event-quotas]

Imported events count toward your monthly event limit:

* If you're close to your monthly limit, imports may be partially skipped
* Skipped events are counted and displayed in the import history
* Consider upgrading your plan if you need to import large amounts of data

### Concurrent Imports [#concurrent-imports]

For cloud users:

* **Maximum 1 active import per organization**
* New imports are blocked until the current one completes
* Maximum 2-hour timeout per import

Self-hosted users have no concurrent import restrictions.

## How to Import Data [#how-to-import-data]

<Steps>
  <Step>
    ### Export Data from Source Platform [#export-data-from-source-platform]

    **Umami:**

    1. Navigate to Settings → Data
    2. Export your data as CSV
    3. Ensure the export includes all required fields

    **Simple Analytics:**

    1. Go to your site settings
    2. Navigate to Export section
    3. Download your analytics data as CSV

    **Plausible:**

    1. Open your site's dashboard
    2. Use the CSV export option to download your data
    3. Keep the exported **ZIP** archive as-is — do not unzip it
  </Step>

  <Step>
    ### Navigate to Import Settings [#navigate-to-import-settings]

    1. Open your Rybbit dashboard
    2. Navigate to Site Settings
    3. Click on the **Import** tab
  </Step>

  <Step>
    ### Select Platform and Upload File [#select-platform-and-upload-file]

    1. Select your source platform from the dropdown
    2. Click "Choose File" and select your exported file (a **CSV** for Umami and Simple Analytics, or a **ZIP** for Plausible)
    3. Click the **Import** button

    <Callout type="warn">
      For very large imports (multiple GB), consider splitting your CSV into smaller files and importing them sequentially.
    </Callout>
  </Step>

  <Step>
    ### Monitor Import Progress [#monitor-import-progress]

    Your import will begin processing in the background. You can:

    * View the import status in the "Import History" section
    * Monitor the number of imported, skipped, and invalid events
    * Continue using Rybbit while the import runs

    <Callout type="info">
      Large imports may take several minutes to complete. The page will automatically refresh to show updated progress.
    </Callout>
  </Step>
</Steps>

## Import History [#import-history]

The Import History section displays all your past and current imports.

### Import Metrics [#import-metrics]

Each import shows three key metrics:

**Imported Events**

* Number of events successfully imported into Rybbit
* These events are now visible in your analytics dashboard

**Skipped Events**

* Events that were excluded during import
* Common reasons:
  * Outside your plan's historical data window
  * Would exceed your monthly event quota

**Invalid Events**

* Events that failed validation during import
* Common reasons:
  * Malformed CSV data
  * Missing required fields
  * Invalid date/time formats
  * Data type mismatches

<Callout type="warn">
  If you see a high number of invalid events, verify your CSV export matches the expected format for your platform.
</Callout>

### Managing Imports [#managing-imports]

**Deleting Completed Imports**

* Click the trash icon next to any completed import
* Confirm the deletion in the dialog
* This will permanently remove the import record **and all associated events** from your analytics
* Active imports cannot be deleted

<Callout type="error">
  Deleting an import removes all events that were imported. This action cannot be undone. Make sure you have a backup of your original CSV file.
</Callout>

## Troubleshooting [#troubleshooting]

### Events Skipped Due to Quota Limits [#events-skipped-due-to-quota-limits]

**Cause:** Importing the events would exceed your monthly event limit.

**Solution:**

* Wait until the next billing cycle when your quota resets
* Upgrade to a plan with a higher event limit
* Import smaller date ranges to stay within quota

### Events Skipped Due to Date Range [#events-skipped-due-to-date-range]

**Cause:** Events are older than your plan's historical data window.

**Solution:**

* Upgrade to Pro plan for 60-month history (vs 24-month on Standard)
* For self-hosted, no action needed - all dates are allowed
* Filter your CSV export to only include recent data

### High Invalid Event Count [#high-invalid-event-count]

**Cause:** CSV format doesn't match the expected structure for your platform.

**Solution:**

1. Verify you selected the correct platform
2. Check that your CSV export includes all required fields
3. Look for special characters or malformed data in the CSV
4. Try importing a small sample file (first 100 rows) to test

### Import Appears Stuck [#import-appears-stuck]

**Cause:** Very large files can take time to process, or a timeout occurred.

**Solution:**

* Wait up to 2 hours for the import to complete
* If still stuck after 2 hours, the import will be automatically marked as complete
* Check the imported event count to see if any data was processed
* Contact support if no events were imported

## Best Practices [#best-practices]

### Before You Import [#before-you-import]

1. **Export a complete backup** from your current analytics platform
2. **Test with a small sample** (first 1,000 rows) before importing your full dataset
3. **Check your event quota** to ensure you have sufficient capacity
4. **Verify date ranges** match your plan's historical window
5. **Review CSV format** matches the required structure for your platform

### During Import [#during-import]

1. **Don't close the browser tab**
2. **Monitor the progress** in the Import History section
3. **Check for skipped/invalid events** early to catch format issues
4. **Wait for completion** before starting another import (cloud users)

### After Import [#after-import]

1. **Verify your data** appears correctly in analytics dashboards
2. **Check date ranges** to ensure historical data is visible
3. **Compare totals** with your source platform to validate accuracy
4. **Keep the original CSV** as a backup before deleting the import


# Definitions (/fr/docs/definitions)



## Aggregate Metrics [#aggregate-metrics]

### Unique Users [#unique-users]

The total number of distinct individuals who visited your website, identified by a unique user ID. Each user is counted only once regardless of how many times they visit.

### Sessions [#sessions]

A series of user interactions with your website within a given time frame. A session ends after 30 minutes of inactivity from the same user ID. Multiple pageviews can occur within one session.

### Pageviews [#pageviews]

The total number of times visitors have viewed pages on your website. Each time a page is loaded or reloaded counts as a pageview.

### Pages Per Session [#pages-per-session]

The average number of pages viewed during a session. Calculated by dividing the total number of pageviews by the total number of sessions.

### Bounce Rate [#bounce-rate]

The percentage of sessions where a user leaves your site after viewing only one page without any interaction. A high bounce rate might indicate that landing pages aren't relevant to visitors.

### Session Duration [#session-duration]

The average length of time users spend on your site during a session. Longer sessions typically indicate more engaged visitors.

## Individual Datapoints [#individual-datapoints]

### User ID [#user-id]

A unique identifier generated from a hash of the visitor's IP address and browser user-agent. This anonymized ID helps track unique visitors without storing personally identifiable information.

### Hostname [#hostname]

The domain name of the website being visited (e.g., example.com).

### Pathname [#pathname]

The path portion of the URL that follows the hostname (e.g., /blog/article).

### Entry Page [#entry-page]

The first page viewed by a user during a session. Identifies which pages commonly serve as entry points to your site.

### Exit Page [#exit-page]

The last page viewed by a user before ending their session. Helps identify where users tend to leave your site.

### Querystring [#querystring]

The portion of a URL that follows a question mark, containing parameters (e.g., ?utm\_source=newsletter).

### Page Title [#page-title]

The title of the webpage as defined in the HTML `<title>` tag.

### Referrer [#referrer]

The URL that a user was on before coming to your site. Shows how users are discovering your content.

### UTM Source [#utm-source]

Identifies which website, search engine, or other source is sending traffic to your site (e.g., google, newsletter, twitter).

### UTM Medium [#utm-medium]

Identifies the marketing medium (e.g., cpc, email, social).

### UTM Term [#utm-term]

Identifies paid search keywords. Used primarily for paid search campaigns.

### UTM Campaign [#utm-campaign]

Identifies the specific campaign or promotion that brought users to your site.

### UTM Content [#utm-content]

Identifies what specifically was clicked to bring the visitor to your site (e.g., banner ad, text link).

### Channel [#channel]

A categorization of traffic sources into standard groups such as direct, search, social, email, or referral.

### Browser [#browser]

The web browser used by the visitor (e.g., Chrome, Firefox, Safari).

### Browser Version [#browser-version]

The specific version of the browser being used.

### Operating System [#operating-system]

The operating system used by the visitor (e.g., Windows, macOS, iOS, Android).

### Operating System Version [#operating-system-version]

The specific version of the operating system being used.

### Language [#language]

The preferred language setting of the visitor's browser.

### Country [#country]

The country where the user is located, based on IP geolocation.

### Region [#region]

The state or region where the user is located, based on IP geolocation.

### City [#city]

The city where the user is located, based on IP geolocation.

### Latitude [#latitude]

The geographic latitude coordinate of the user's approximate location.

### Longitude [#longitude]

The geographic longitude coordinate of the user's approximate location.

### Screen Width [#screen-width]

The width of the visitor's screen or device viewport in pixels.

### Screen Height [#screen-height]

The height of the visitor's screen or device viewport in pixels.

### Device Type [#device-type]

The type of device being used (e.g., desktop, tablet, mobile).

### Event Name [#event-name]

The name of a custom event triggered by user interaction (e.g., "button\_click", "form\_submit").

### Event Properties [#event-properties]

Additional contextual data associated with custom events, stored as key-value pairs. Used to provide more detail about specific interactions.


# Embeds (/fr/docs/embed-widget)



Rybbit supports two iframe embed options:

* [Widget Embeds](/docs/embeds/widget) show a compact live visitor widget on any web page.
* [Dashboard Embed](/docs/embeds/dashboard) shows your analytics dashboard in an iframe.

Both embeds are self-contained iframes. There is no script tag, no JavaScript on your site, and no dependency on the Rybbit tracking script.

## Which Embed Should I Use? [#which-embed-should-i-use]

Use [Widget Embeds](/docs/embeds/widget) when you want a small live visitor count, chart, or top-countries summary. Widget Embeds do not make your dashboard public.

Use [Dashboard Embed](/docs/embeds/dashboard) when you want to publish the full read-only analytics dashboard. Dashboard Embed uses a generated private link, so Public Analytics is not required.


# Experiments (/fr/docs/experiments)





Experiments are A/B tests built on top of Rybbit. Each experiment splits your visitors across the variants of a [multivariate feature flag](/docs/feature-flags), then measures how often each variant completes a [conversion goal](/docs/goals). Rybbit calculates the conversion rate for every variant, the **lift** relative to your control, and how confident you can be that the difference is real.

<Callout type="info">
  An experiment ties together two features you may already use: a **multivariate feature flag** decides which variant each visitor sees, and a **goal** defines the conversion you are optimizing for. If you understand those two pieces, you understand experiments.
</Callout>

## How Experiments Work [#how-experiments-work]

An experiment has three moving parts:

| Part           | What it does                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assignment** | A multivariate feature flag assigns each visitor to one stable variant (for example `control` or `variant_a`) based on its rollout percentages.                                                   |
| **Exposure**   | When your code reads the flag with `rybbit.flag()`, Rybbit records an exposure for that variant. The number of distinct sessions exposed to a variant is the denominator for its conversion rate. |
| **Conversion** | The experiment's primary goal — a page visit or a custom event — counts as a conversion for whichever variant the visitor was assigned.                                                           |

Because assignment is sticky for a given visitor, a person sees the same variant on repeat visits, which keeps your results consistent.

## Creating an Experiment [#creating-an-experiment]

Open your site in the Rybbit dashboard, go to **Experiments**, and click **New experiment**. A guided wizard walks you through each step.

<Steps>
  <Step>
    ### Basics [#basics]

    Give the experiment a **name** and, optionally, a **hypothesis** and **description*&#x2A;. The hypothesis is internal context for your team — something like &#x2A;"Changing the CTA copy will increase signups."* It does not affect assignment or tracking.

    New experiments are created as **drafts** so you can add the implementation code before any traffic is split.
  </Step>

  <Step>
    ### Assignment [#assignment]

    Choose how visitors are split into variants:

    * **Create a new flag** — Define a new multivariate flag with its own variants and rollout split. Each variant needs a unique key, and the rollout percentages must add up to &#x2A;*100%**.
    * **Use an existing flag** — Pick a multivariate flag that is not already attached to another experiment.

    <Callout type="info">
      Each experiment uses its own multivariate flag. The flag's variant keys (such as `control` and `variant_a`) are what you branch on in code.
    </Callout>
  </Step>

  <Step>
    ### Goal [#goal]

    Pick the conversion you want to compare variants against:

    * **Create a new goal** — Define a **page goal** (a URL path such as `/signup/complete`) or an **event goal** (a custom event such as `signup_completed`). The form provides autocomplete suggestions based on paths and events already seen on your site.
    * **Use an existing goal** — Connect a goal you already track.
    * **Skip for now** — Create the experiment without a goal and add one later. Conversion results require a goal.
  </Step>

  <Step>
    ### Review and Implement [#review-and-implement]

    Review the assignment flag and goal, then create the experiment. Rybbit creates any new flag or goal you configured, connects them, and shows you the **implementation code** for the flag. The experiment stays in **draft** until you start it from the experiment list.
  </Step>
</Steps>

## Implementing in Code [#implementing-in-code]

Read the experiment's flag in your app and branch your UI or behavior on the returned variant. Reading the flag also records the exposure that powers your results, so make sure it runs wherever the tested experience is shown.

<Tabs items="['JavaScript', 'TypeScript']">
  <Tab value="JavaScript">
    ```javascript
    window.rybbit.onReady((rybbit) => {
      const variant = rybbit.flag("checkout_cta", "control");

      if (variant === "variant_a") {
        // Render the variant experience.
      } else {
        // Render the control experience.
      }
    });
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript
    type ExperimentVariant = "control" | "variant_a";

    window.rybbit.onReady((rybbit) => {
      const variant = rybbit.flag("checkout_cta", "control") as ExperimentVariant;

      switch (variant) {
        case "variant_a":
          // Render the variant experience.
          break;
        default:
          // Render the control experience.
          break;
      }
    });
    ```
  </Tab>
</Tabs>

If your primary goal is an **event goal**, fire that event when the conversion action happens:

```javascript
window.rybbit.onReady((rybbit) => {
  rybbit.event("signup_completed");
});
```

**Page goals** need no extra code — Rybbit counts sessions that reach the goal's path automatically.

<Callout type="info">
  Use a stable variant for the `rybbit.flag()` fallback (usually `"control"`) so visitors still get a sensible experience before the flag resolves or if the experiment is paused.
</Callout>

## Reading Results [#reading-results]

Each experiment shows a results panel comparing every variant. Results respect the global date range and filters applied on the page.

| Metric              | Description                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Variant**         | The variant key, with the **Control** marked as the baseline.                                                         |
| **Sessions**        | Sessions exposed to that variant, alongside the number that converted.                                                |
| **Conversion rate** | Conversions divided by the number of exposed sessions (the **Sessions** figure) for that variant.                     |
| **Lift**            | The percentage change in conversion rate relative to the control. Positive lift is shown in green, negative in red.   |
| **Confidence**      | How confident Rybbit is that the variant's difference from the control is real, based on a two-proportion comparison. |

Rybbit summarizes the state of each experiment at a glance:

* **Gathering data** — Not enough exposures or conversions yet to draw a conclusion.
* **Leading** — A variant is outperforming the control with at least **95% confidence**.
* **Winner** — The variant recorded as the winner once the experiment is decided.

<Callout type="warn">
  Avoid stopping an experiment the moment a variant looks ahead. Let it run until it reaches 95% confidence with a meaningful number of conversions, otherwise early noise can masquerade as a real difference.
</Callout>

## Experiment Lifecycle [#experiment-lifecycle]

Experiments move through four statuses, which you control from the experiment list:

| Status        | Meaning                                                                                 |
| ------------- | --------------------------------------------------------------------------------------- |
| **Draft**     | Created but not yet collecting results. Add your implementation code here.              |
| **Running**   | Actively splitting traffic and recording exposures and conversions.                     |
| **Paused**    | Temporarily stopped. Visitors keep their existing assignments.                          |
| **Completed** | Finished. Use this once you have a result and have shipped (or rolled back) the change. |

Use **Start**, **Pause**, and **Complete** on each experiment to move between states.

## Best Practices [#best-practices]

* Change one thing at a time so you can attribute any lift to a single difference.
* Make sure your variant rollout percentages add up to 100% unless you intentionally want unassigned traffic.
* Read the flag wherever the tested experience renders so every exposed visitor is counted.
* Pick a primary goal that directly reflects the outcome you care about, not a proxy metric.
* Wait for 95% confidence and a healthy sample size before declaring a winner.
* After completing an experiment, ship the winning variant and remove the flag branch to keep your code clean.

***

**Related Documentation:**

* [Feature Flags](/docs/feature-flags) — The assignment mechanism behind experiments
* [Goals](/docs/goals) — Define the conversion an experiment measures
* [Track Events](/docs/track-events) — Fire custom events for event goals
* [Tracking Script](/docs/script) — Load the script and use `onReady()`


# Feature Flags (/fr/docs/feature-flags)





Feature flags let you change product behavior without deploying new code. In Rybbit, a flag can be evaluated in the browser, on your server, or in both places. Flag assignments are also attached to analytics events so you can filter and compare behavior by flag value.

<Callout type="info">
  Feature flags are different from [tags](/docs/tagging). Tags label traffic that you already routed yourself. Feature flags decide which value a visitor receives at runtime.
</Callout>

## Create a Flag [#create-a-flag]

1. Open your site in the Rybbit dashboard.
2. Go to **Feature Flags**.
3. Click **New flag**.
4. Choose a stable **key**, such as `new_checkout` or `pricing_banner`.
5. Select the flag type, runtime, and targeting conditions.
6. Enable the flag when you are ready for it to evaluate as active.

The **key** is the public identifier used in code. Treat it as the flag name and avoid changing it after the flag is in use.

## Flag Types [#flag-types]

| Type                  | Returns                                         | Best for                                                                  |
| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
| **Boolean**           | `true` or `false`                               | Releasing a feature on/off, gradual rollouts, allowlists                  |
| **Multiple variants** | A variant key like `"control"` or `"variant_a"` | Comparing more than one experience or configuration                       |
| **Remote config**     | `true` plus a payload from `flagPayload()`      | Shipping structured config such as copy, colors, limits, or JSON settings |

### Boolean Flags [#boolean-flags]

Boolean flags support a rollout percentage for each condition set. If the visitor matches the condition set and falls inside the rollout bucket, `window.rybbit.flag()` returns `true`.

```javascript
window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);

  if (enabled) {
    showNewCheckout();
  }
});
```

### Multiple Variants [#multiple-variants]

Multiple variant flags return the selected variant key. Each variant has its own rollout percentage and optional payload.

```javascript
window.rybbit.onReady((rybbit) => {
  const variant = rybbit.flag("homepage_cta", "control");

  if (variant === "variant_a") {
    renderAlternateCTA();
  }
});
```

Variant rollout percentages are evaluated in order. If the visitor falls outside the total allocated percentage, the flag returns `false`.

### Remote Config [#remote-config]

Remote config flags are useful when you want Rybbit to choose a JSON payload. For remote config, `flag()` returns whether a config matched, and `flagPayload()` returns the actual config.

```javascript
window.rybbit.onReady((rybbit) => {
  const config = rybbit.flagPayload("checkout_config", {
    buttonText: "Continue",
    theme: "default",
  });

  renderCheckout(config);
});
```

Remote config can still use targeting. This lets you serve one config to beta users, another config to a country, and a default config to everyone else.

## Runtime [#runtime]

Each flag has a runtime:

| Runtime    | Evaluated by                 | Use when                                                       |
| ---------- | ---------------------------- | -------------------------------------------------------------- |
| **Client** | The browser tracking script  | UI changes, frontend copy, client-only experiments             |
| **Server** | Your backend through the API | Backend behavior, pricing logic, data access, anything private |
| **Both**   | Browser and server           | Both sides need the same decision                              |

<Callout type="warn">
  Do not put secrets in client or both-runtime flag payloads. Browser-evaluated flags and payloads are visible to the user.
</Callout>

## Targeting and Condition Sets [#targeting-and-condition-sets]

Flags use ordered condition sets. Each set contains targeting rules plus the rollout, variants, or payload for users who match that set.

Evaluation works like this:

1. Rybbit checks condition sets from top to bottom.
2. The first condition set whose rules all match is selected.
3. Rybbit applies the rollout, variant allocation, or remote config payload from that selected set.
4. Later condition sets are not evaluated.

This means condition set order matters. Put narrow segments first and broad defaults last.

<Callout type="warn">
  If a visitor matches a boolean condition set but falls outside that set's rollout percentage, Rybbit returns `false` and does not continue to later condition sets.
</Callout>

### Targeting Fields [#targeting-fields]

| Field           | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| Hostname        | Current hostname, such as `example.com`                          |
| Pathname        | Current path, such as `/pricing`                                 |
| Query parameter | A specific URL query parameter                                   |
| Referrer        | The document referrer                                            |
| Language        | Browser language, such as `en-US`                                |
| Country         | Visitor country resolved from IP                                 |
| Region          | Visitor region resolved from IP                                  |
| City            | Visitor city resolved from IP                                    |
| Device type     | Device category derived from user agent and screen size          |
| User ID         | The identified user ID, falling back to the anonymous visitor ID |
| User trait      | A trait set through `identify()` or `setTraits()`                |

### Operators [#operators]

Targeting rules support:

* `equals`
* `not_equals`
* `contains`
* `starts_with`
* `ends_with`
* `regex`

All rules in a condition set must match. Multiple condition sets act as ordered alternatives.

## Browser Runtime [#browser-runtime]

The tracking script automatically evaluates client and both-runtime flags when it loads. It sends context such as anonymous visitor ID, identified user ID, URL, referrer, language, screen size, IP-derived location, and saved user traits.

Use `onReady()` before reading flags if you need the evaluated value during page initialization:

```javascript
window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);
  const payload = rybbit.flagPayload("new_checkout", {});
});
```

Available browser methods:

<TypeTable
  type="{
  &#x22;flag(key, fallback)&#x22;: {
    description: &#x22;Returns a single flag value. Reading a flag also records a feature flag exposure event once per flag value/version.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flagPayload(key, fallback)&#x22;: {
    description: &#x22;Returns the payload for a flag or variant. Use this for remote config and multivariate payloads.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flags()&#x22;: {
    description: &#x22;Returns all evaluated flag values keyed by flag key.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flagPayloads()&#x22;: {
    description: &#x22;Returns all available flag payloads keyed by flag key.&#x22;,
    type: &#x22;function&#x22;,
  },
}"
/>

Assignments are included on analytics events as a feature flag map. This lets you filter dashboard reports by flag key and value.

### Identify and Traits [#identify-and-traits]

If you call `identify()` or `setTraits()`, the browser runtime refreshes feature flags using the updated user context.

```javascript
window.rybbit.identify("user_123", {
  plan: "pro",
  beta: true,
});
```

You can then target flags using **User ID** or **User trait** rules.

## Server Runtime [#server-runtime]

Use server runtime for decisions that should not happen in the browser. The server endpoint returns server and both-runtime flags only.

```
POST /api/sites/:siteId/feature-flags/evaluate
```

### Request [#request]

<TypeTable
  type="{
  anonymousId: {
    description: &#x22;Stable anonymous visitor ID used for rollout bucketing. Keep this stable for sticky assignments.&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  identifiedUserId: {
    description: &#x22;Logged-in user ID. Enables user ID rules and loads saved user traits.&#x22;,
    type: &#x22;string&#x22;,
  },
  hostname: {
    description: &#x22;Hostname used by hostname targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  pathname: {
    description: &#x22;Path used by pathname targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  query: {
    description: &#x22;Parsed query parameter object used by query targeting rules.&#x22;,
    type: &#x22;Record<string, string>&#x22;,
  },
  querystring: {
    description: &#x22;Raw query string. Used if query is not provided.&#x22;,
    type: &#x22;string&#x22;,
  },
  referrer: {
    description: &#x22;Referrer used by referrer targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  language: {
    description: &#x22;Language code used by language targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  screenWidth: {
    description: &#x22;Screen width used with user agent parsing to derive device type.&#x22;,
    type: &#x22;number&#x22;,
  },
  screenHeight: {
    description: &#x22;Screen height used with user agent parsing to derive device type.&#x22;,
    type: &#x22;number&#x22;,
  },
}"
/>

<Tabs items="['cURL', 'JavaScript']">
  <Tab value="cURL">
    ```bash
    curl -X POST "https://app.rybbit.io/api/sites/123/feature-flags/evaluate" \
      -H "Authorization: Bearer rb_your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "anonymousId": "visitor_abc",
        "identifiedUserId": "user_123",
        "hostname": "example.com",
        "pathname": "/checkout",
        "query": { "plan": "pro" },
        "language": "en-US",
        "screenWidth": 1440,
        "screenHeight": 900
      }'
    ```
  </Tab>

  <Tab value="JavaScript">
    ```javascript
    const response = await fetch(
      "https://app.rybbit.io/api/sites/123/feature-flags/evaluate",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer rb_your_api_key_here",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          anonymousId: "visitor_abc",
          identifiedUserId: "user_123",
          hostname: "example.com",
          pathname: "/checkout",
          query: { plan: "pro" },
          language: "en-US",
          screenWidth: 1440,
          screenHeight: 900,
        }),
      }
    );

    const data = await response.json();
    const newCheckout = data.flags.new_checkout?.value === true;
    ```
  </Tab>
</Tabs>

### Response [#response]

```json
{
  "flags": {
    "new_checkout": {
      "key": "new_checkout",
      "value": true,
      "flagType": "boolean",
      "payload": { "copy": "Try it now" },
      "conditionSet": "Default",
      "version": 3,
      "reason": "rollout",
      "matched": true,
      "rolloutPercentage": 100
    }
  },
  "generatedAt": "2026-05-27T12:00:00.000Z"
}
```

Assignment fields:

| Field               | Description                                                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`             | The evaluated flag value. Boolean flags return `true` or `false`; multiple variant flags return a variant key or `false`; remote config returns `true` when matched. |
| `payload`           | Optional payload from the selected condition set or selected variant.                                                                                                |
| `variant`           | Selected variant key for multiple variant flags.                                                                                                                     |
| `conditionSet`      | Name of the condition set that matched.                                                                                                                              |
| `reason`            | Why the assignment was produced, such as `rollout`, `variant`, `remote_config`, `fallthrough`, `target_mismatch`, or `disabled`.                                     |
| `matched`           | Whether the flag produced an active match.                                                                                                                           |
| `rolloutPercentage` | The rollout percentage that was evaluated.                                                                                                                           |
| `version`           | Flag version. Increments when the flag is edited.                                                                                                                    |

## Analytics and Filtering [#analytics-and-filtering]

Feature flag assignments are stored on events. Browser-tracked events include evaluated client flags automatically. Server-side events can include a `feature_flags` object in the [HTTP API](/docs/api/sending-events) payload:

```json
{
  "site_id": "123",
  "type": "custom_event",
  "event_name": "purchase",
  "pathname": "/checkout",
  "feature_flags": {
    "new_checkout": "true",
    "homepage_cta": "variant_a"
  }
}
```

Use feature flag filters in the dashboard to compare behavior between flag values.

## Best Practices [#best-practices]

* Keep flag keys stable and descriptive, such as `new_checkout` or `pricing_page_copy`.
* Use **Client** runtime only for values that are safe to expose in the browser.
* Use **Server** runtime for permission checks, pricing logic, and private backend behavior.
* Put specific condition sets before broad default condition sets.
* Keep remote config payloads small and JSON-serializable.
* Use a stable `anonymousId` for server-side evaluation so rollout assignments remain sticky.
* Remove stale flags after rollout is complete to keep your dashboard and codebase clean.

**Related Documentation:**

* [Tracking Script](/docs/script)
* [Identify Users](/docs/identify-users)
* [Tagging](/docs/tagging)
* [API - Sending Events](/docs/api/sending-events)


# Filter traffic (/fr/docs/filter-traffic)





Rybbit provides server-side traffic filtering to keep unwanted data out of your analytics. You can exclude your own traffic, staging and preview environments, internal tools, monitoring checks, or entire countries.

Filters are configured from **Site Settings → Exclusions**.

## Available Filters [#available-filters]

| Filter                    | Use it for                                                            | Matching behavior                                         | Limit       |
| ------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- | ----------- |
| **IP Exclusions**         | Your home, office, VPN, or internal network traffic                   | Single IPs, CIDR ranges, and IPv4 ranges                  | 100 entries |
| **Country Exclusions**    | Regional filtering or compliance requirements                         | Two-letter ISO country codes, such as `US`, `GB`, or `DE` | 250 entries |
| **Path Exclusions**       | Admin pages, private pages, preview routes, or test pages             | Case-insensitive glob patterns using `*`                  | 100 entries |
| **Hostname Exclusions**   | Localhost, staging domains, preview deployments, or temporary domains | Case-insensitive glob patterns using `*`                  | 100 entries |
| **User Agent Exclusions** | Monitoring tools, headless browsers, or custom crawlers               | Case-insensitive substring matching                       | 100 entries |

When a request matches an exclusion, Rybbit returns a successful response but does not write the event to analytics storage.

## IP Exclusions [#ip-exclusions]

Block traffic from specific IP addresses or ranges at the server level. This is usually the best way to hide your own traffic.

Supported formats:

* **Single IPv4**: `192.168.1.1`
* **Single IPv6**: `2001:db8::1`
* **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`
* **IPv4 ranges**: `192.168.1.1-192.168.1.10`

For setup instructions and best practices, see [Hiding Your Own Traffic](/docs/hiding-own-traffic).

## Country Exclusions [#country-exclusions]

Block all traffic geolocated to specific countries. Rybbit resolves the visitor IP address with the MaxMind GeoLite2 database, then compares the resulting country code to your exclusion list.

Use two-letter ISO country codes:

* `US` for United States
* `GB` for United Kingdom
* `CN` for China
* `DE` for Germany

Country codes are stored as uppercase values in the dashboard and API.

<Callout type="warning">
  **Private IP addresses**: Country exclusion cannot work for private IP addresses such as `127.0.0.1`, `192.168.x.x`, `10.x.x.x`, or `172.16.x.x` because they cannot be geolocated. This includes localhost and Docker container IPs during local development.
</Callout>

<Callout type="info">
  **VPNs and proxies**: Visitors using VPNs or proxies are detected based on the VPN or proxy server location, not their physical location.
</Callout>

## Path Exclusions [#path-exclusions]

Exclude traffic to specific page paths. Path exclusions match the pathname only, not the query string.

Examples:

```txt
/admin/*
/preview
/internal/*
```

Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `/admin/*` matches `/admin/users` and `/admin/settings`.

Use path exclusions for pages that should not appear in analytics at all, such as admin dashboards, internal previews, or test routes.

<Callout type="info">
  For client-side-only pageview skipping, you can also use the tracking script's `data-skip-patterns` option. Site-level path exclusions are enforced on the server and also apply to session replay ingestion.
</Callout>

## Hostname Exclusions [#hostname-exclusions]

Exclude traffic from specific hostnames. This is useful when the same site ID is used across production, staging, preview, and local environments.

Examples:

```txt
localhost
staging.example.com
*.vercel.app
*.netlify.app
```

Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `*.vercel.app` matches `my-preview.vercel.app` but not `vercel.app`.

## User Agent Exclusions [#user-agent-exclusions]

Exclude traffic from requests whose user agent contains a configured substring.

Examples:

```txt
HeadlessChrome
MyMonitor
Pingdom
```

Matching is case-insensitive and uses substring matching, so `HeadlessChrome` matches `Mozilla/5.0 HeadlessChrome/120`.

Use user-agent exclusions for uptime monitors, synthetic checks, internal crawlers, or other tools with predictable user-agent strings.

## What Filters Apply To [#what-filters-apply-to]

Traffic filters run before normal analytics data is stored. They apply to:

* Pageviews
* Custom events
* Performance and Web Vitals events
* Error events
* Autocapture events
* Session replay batches

## How Filters Are Evaluated [#how-filters-are-evaluated]

Rybbit checks exclusions in this order:

1. IP address
2. Country
3. Path
4. Hostname
5. User agent

If any filter matches, the event is accepted with a `200` response but is not tracked. Changes usually take effect within 60 seconds because site configuration is cached briefly on the server.

## Testing Filters Locally [#testing-filters-locally]

To test country filtering locally, send a public IP through the `X-Real-IP` header:

```bash
curl -X POST http://localhost:3001/api/track \
  -H "Content-Type: application/json" \
  -H "X-Real-IP: 8.8.8.8" \
  -d '{
    "type": "pageview",
    "site_id": "your-site-id",
    "hostname": "example.com",
    "pathname": "/test"
  }'
```

For path and hostname filters, set `pathname` and `hostname` in the event payload to values that should match your configured exclusions.


# Funnels (/fr/docs/funnels)













<img alt="Funnels Dashboard" src="__img0" />

Funnels let you define a sequence of steps — page visits, custom events, or autocaptured interactions — and measure how many users progress through each stage. You can see where users convert, where they drop off, and drill into the sessions at each step to understand why.

## Creating a Funnel [#creating-a-funnel]

<img alt="Creating a Funnel" src="__img1" />

<Steps>
  <Step>
    ### Click "Create Funnel" [#click-create-funnel]

    Each funnel has:

    * **Name** — A label for the funnel (e.g., "Signup Flow", "Checkout Process")
    * **Steps** — Two or more sequential steps, each tracking a page visit, custom event, outbound link, button click, form submission, or copy event
  </Step>

  <Step>
    ### Add Steps [#add-steps]

    A funnel always must have at least two steps.

    There are six types of funnel steps. Path and custom event steps require a value. For the four autocaptured interaction types, the pattern is optional—leave it empty to match every interaction of that type.

    <Tabs items="['Path', 'Custom Event', 'Outbound Link', 'Button Click', 'Form Submit', 'Copy']">
      <Tab value="Path">
        Path steps match pageview events by URL path.

        * Enter a URL path starting with `/`
        * Wildcards are supported:
          * `*` matches a single path segment — `/products/*` matches `/products/shoes`
          * `**` matches multiple segments — `/docs/**` matches `/docs/api/v2/intro`
      </Tab>

      <Tab value="Custom Event">
        Custom event steps match events by name (e.g., `add_to_cart`, `purchase_completed`).

        Events must be tracked using the Rybbit tracking script. See [Track Events](/docs/track-events) for setup instructions.
      </Tab>

      <Tab value="Outbound Link">
        Outbound link steps match clicks on links that lead away from your site.

        * Enter a destination URL pattern such as `https://example.com/pricing` or `https://*.example.com/**`
        * Leave the pattern empty to match any outbound click

        Outbound link tracking is enabled by default.
      </Tab>

      <Tab value="Button Click">
        Button click steps match clicks on buttons, button/submit inputs, and elements with `role="button"`.

        * Enter a visible button-text pattern such as `Sign Up` or `Start * Trial`
        * Leave the pattern empty to match any button click

        Buttons that already use `data-rybbit-event` are recorded as custom events instead.
      </Tab>

      <Tab value="Form Submit">
        Form submit steps match submissions of HTML forms.

        * Enter a form name or ID pattern such as `signup-form`
        * The pattern can also match the form's action URL
        * Leave the pattern empty to match any form submission
      </Tab>

      <Tab value="Copy">
        Copy steps match text that visitors copy from your site.

        * Enter a copied-text pattern such as `PROMO*`
        * Leave the pattern empty to match any copied text
      </Tab>
    </Tabs>

    Autocaptured interaction patterns support wildcards: `*` matches one or more characters and `**` also matches an empty value. The form suggests values already observed on your site.

    <Callout type="info" title="Enable autocapture first">
      Button click, form interaction, and copy tracking are disabled by default. Enable the event types you want to use in the **Tracking** tab of your site settings. Only interactions collected after tracking is enabled can appear in a funnel. See [Autocapture](/docs/autocapture) for the properties collected with each type.
    </Callout>
  </Step>

  <Step>
    ### Configure Step Options (optional) [#configure-step-options-optional]

        <img alt="Step Options" src="__img2" />

    Each step has additional configuration options:

    * **Label** (optional) — A friendly display name for the step
    * **Hostname** (optional) — Restrict matching to a specific domain, useful for multi-domain sites
    * **Property Filters** (optional) — Filter by URL parameters (for path steps) or event properties (for all other step types). Multiple filters can be added per step, and all must match.
  </Step>
</Steps>

## Reading Funnel Results [#reading-funnel-results]

The funnel visualization updates in real time as you configure steps. For each step, you'll see:

* **Sessions** — How many sessions reached this step
* **Conversion Rate** — Percentage of the first step's sessions that reached this step
* **Dropped** — How many sessions completed the previous step but not this one
* **Dropoff Rate** — Percentage of the previous step's sessions lost at this point

The horizontal bar for each step shows two layers:

* **Solid bar** — Overall conversion from the first step
* **Striped overlay** — Conversion from the immediately previous step

Steps are evaluated sequentially — each step must occur after the previous one within the same session.

## Viewing Sessions [#viewing-sessions]

<img alt="Viewing Sessions" src="__img3" />

Click any step to expand it and view the sessions associated with that step:

* **Reached** tab — Sessions that completed this step
* **Dropped Off** tab — Sessions that reached the previous step but didn't make it to this one (available for step 2 and beyond)

Each session shows entry/exit pages, duration, location, device info, referrer, UTM parameters, and user ID if identified. Sessions are paginated.

***

**Related Documentation:**

* [Autocapture](/docs/autocapture) — Configure automatically captured interactions
* [Goals](/docs/goals) — Track single-action conversions
* [Track Events](/docs/track-events) — Set up custom event tracking


# Goals (/fr/docs/goals)













<img alt="Goals Dashboard" src="__img0" />

Goals let you define specific actions — from visiting a page to clicking a button — and measure how often your visitors complete them. Each goal tracks a conversion rate against total sessions, giving you a clear picture of how effectively your site drives key outcomes.

## Creating a Goal [#creating-a-goal]

<img alt="Creating a Goal" src="__img1" />

<Steps>
  <Step>
    ### Click "Create Goal" [#click-create-goal]

    Every goal has:

    * **Name** (optional) — A friendly label like "Completed Checkout" or "Signed Up"
    * **Type** — Page, custom event, outbound link, button click, form submission, or copied text
    * **Value** — A required path or custom event name, or an optional pattern that narrows an autocaptured interaction
  </Step>

  <Step>
    ### Choose a Goal Type [#choose-a-goal-type]

    There are six goal types. Page and custom event goals require a value. For the four autocaptured interaction types, the pattern is optional—leave it empty to count every interaction of that type.

    <Tabs items="['Page', 'Custom Event', 'Outbound Link', 'Button Click', 'Form Submit', 'Copy']">
      <Tab value="Page">
        Page goals track when a user visits a URL matching a given path pattern.

        * The value must be a path starting with `/` (not a full URL)
        * Wildcards are supported:
          * `*` matches a single path segment — `/blog/*` matches `/blog/my-post`
          * `**` matches multiple segments — `/docs/**` matches `/docs/api/v2/intro`

        The form provides autocomplete suggestions based on actual paths seen on your site.
      </Tab>

      <Tab value="Custom Event">
        Custom event goals track when an event with a specific name is fired. The value is the event name (e.g., `signup_clicked`, `purchase_completed`).

        Events must be tracked using the Rybbit tracking script. See [Track Events](/docs/track-events) for setup instructions.
      </Tab>

      <Tab value="Outbound Link">
        Outbound link goals track clicks on links that lead away from your site.

        * Enter a destination URL pattern such as `https://example.com/pricing` or `https://*.example.com/**`
        * Leave the pattern empty to count clicks to any external URL

        Outbound link tracking is enabled by default.
      </Tab>

      <Tab value="Button Click">
        Button click goals track clicks on buttons, button/submit inputs, and elements with `role="button"`.

        * Enter a visible button-text pattern such as `Sign Up` or `Start * Trial`
        * Leave the pattern empty to count any button click

        Buttons that already use `data-rybbit-event` are recorded as custom events instead.
      </Tab>

      <Tab value="Form Submit">
        Form submit goals track submissions of HTML forms.

        * Enter a form name or ID pattern such as `signup-form`
        * The pattern can also match the form's action URL
        * Leave the pattern empty to count any form submission
      </Tab>

      <Tab value="Copy">
        Copy goals track text that visitors copy from your site.

        * Enter a copied-text pattern such as `PROMO*`
        * Leave the pattern empty to count any copied text
      </Tab>
    </Tabs>

    Autocaptured interaction patterns support wildcards: `*` matches one or more characters and `**` also matches an empty value. The form suggests values already observed on your site.

    <Callout type="info" title="Enable autocapture first">
      Button click, form interaction, and copy tracking are disabled by default. Enable the event types you want to use in the **Tracking** tab of your site settings. Only interactions collected after tracking is enabled can count toward a goal. See [Autocapture](/docs/autocapture) for the properties collected with each type.
    </Callout>
  </Step>

  <Step>
    ### Add Property Filters (optional) [#add-property-filters-optional]

        <img alt="Property Filters" src="__img2" />

    You can narrow a goal to only count conversions when specific properties match:

    * **Page goals** — Filter by URL parameters (e.g., only count visits where `utm_source=adwords`)
    * **Custom event goals** — Filter by event properties (e.g., only count events where `plan=premium`)
    * **Autocaptured interaction goals** — Filter by captured properties such as `url`, `text`, `formName`, `formId`, or `formAction`

    Toggle **Match specific URL parameters** or **Match specific event properties** to add filters. You can add multiple filters per goal — all filters must match for a session to count as a conversion.
  </Step>
</Steps>

## Goal Metrics [#goal-metrics]

Each goal card displays:

* **Total Conversions** — The number of distinct sessions that completed the goal
* **Conversion Rate** — Conversions divided by total sessions in the selected time period, shown as a percentage with a visual progress bar

Goals respect the global date range and filters (country, device, browser, etc.) applied on the page.

## Viewing Converted Sessions [#viewing-converted-sessions]

<img alt="Viewing Converted Sessions" src="__img3" />

Click a goal card to expand it and see the sessions that converted. Each session shows:

* Entry and exit pages
* Session duration
* Location (country, region, city)
* Device, browser, and OS
* Referrer, channel, and UTM parameters
* User ID (if identified)

Sessions are sorted by most recent first and paginated.

***

**Related Documentation:**

* [Autocapture](/docs/autocapture) — Configure automatically captured interactions
* [Track Events](/docs/track-events) — Set up custom event tracking
* [Funnels](/docs/funnels) — Analyze multi-step conversion paths


# Hiding your own traffic (/fr/docs/hiding-own-traffic)





There are several ways to disable Rybbit tracking to hide your own visits from analytics.

<Tabs items="['IP Exclusion', 'Browser Extensions', 'localStorage Method']">
  <Tab>
    **IP Exclusion (Recommended)**: Block traffic from specific IP addresses or ranges at the server level for complete accuracy.

    ### Setting Up IP Exclusion [#setting-up-ip-exclusion]

    1. **Navigate to Site Settings**: Go to your site's settings page in the Rybbit dashboard
    2. **Find IP Exclusions section**: Scroll down to the "IP Exclusions" configuration
    3. **Add your IP addresses**: Enter the IP addresses or ranges you want to exclude

    ### Supported IP Formats [#supported-ip-formats]

    Rybbit supports multiple IP exclusion formats:

    * **Single IPv4**: `192.168.1.1`
    * **Single IPv6**: `2001:db8::1`, `::1`
    * **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`
    * **IPv4 ranges**: `192.168.1.1-192.168.1.10` (IPv4 only)

    ### Examples [#examples]

    ```
    # Your home IP address
    203.0.113.45

    # Your office network (CIDR)
    203.0.113.0/24

    # IP range for your team
    198.51.100.10-198.51.100.20

    # IPv6 address
    2001:db8::1
    ```

    ### Key Features [#key-features]

    * **Server-side filtering**: Traffic is blocked before it reaches your analytics, providing highly accurate exclusion
    * **Multiple formats**: Supports individual IPs, CIDR notation, and ranges
    * **IPv4 and IPv6**: Full support for both IP versions
    * **Near real-time updates**: Changes take effect within seconds
    * **No browser dependency**: Works regardless of browser or device

    <Callout type="info">
      **IP Stability Note**: IP addresses can change due to factors like mobile networks, VPN usage, ISP changes, and IPv6 privacy extensions. You may need to periodically update your excluded IPs to maintain effective filtering.
    </Callout>

    <Callout type="info">
      **Dynamic IP Addresses**: If you frequently use VPNs, mobile networks, or have a dynamic IP address that changes regularly, consider these approaches:

      * Use CIDR ranges that cover your typical IP pool (consult your ISP or VPN provider)
      * Combine IP exclusion with browser extensions for comprehensive coverage
      * Check your current IP periodically and update exclusions as needed
      * For corporate networks, exclude the entire office IP range rather than individual addresses
    </Callout>

    <Callout type="warning">
      **Note**: IPv6 range notation (e.g., `2001:db8::1-2001:db8::ff`) is not supported. Use CIDR notation instead (e.g., `2001:db8::/32`).
    </Callout>

    <Callout type="info">
      **Finding your IP**: You can find your current IP address by visiting sites like [whatismyipaddress.com](https://whatismyipaddress.com) or [ipinfo.io](https://ipinfo.io).
    </Callout>
  </Tab>

  <Tab>
    **Browser Extensions**: Easy client-side solution using community-maintained browser extensions.

    ### Available Extensions [#available-extensions]

    * **[Chrome Extension](https://chrome.google.com/webstore/detail/gofnfdfidbkpellionhpmkejgaajieoo)**: Install from the Chrome Web Store
    * **[Firefox Extension](https://addons.mozilla.org/en-US/firefox/addon/rybbit-opt-out/)**: Install from Firefox Add-ons

    These extensions automatically disable Rybbit tracking on all websites where you have Rybbit installed, without requiring any manual configuration.

    <Callout type="info">
      **Self-hosted users**: These extensions require Rybbit version 1.1.0 or higher. If you're running an older version, please update your installation or use the localStorage method.
    </Callout>

    *These extensions are community-maintained by [@davidfiala](https://github.com/davidfiala).*
  </Tab>

  <Tab>
    **localStorage Method**: Manual configuration using your browser's developer console for more granular control.

    <Steps>
      ### 1. Open your browser's developer console [#1-open-your-browsers-developer-console]

      Press **F12** or right-click the page and select "Inspect"

      Navigate to the "Console" tab

      ### 2. Disable tracking [#2-disable-tracking]

      Enter this command to disable tracking:

      ```js
      localStorage.setItem('disable-rybbit', 'true');
      ```

      ### 3. Re-enable tracking (when needed) [#3-re-enable-tracking-when-needed]

      If you want to re-enable tracking later, enter:

      ```js
      localStorage.removeItem('disable-rybbit');
      ```
    </Steps>
  </Tab>
</Tabs>

## Summary [#summary]

Multiple methods are available for hiding your own traffic, each with different advantages:

* **IP exclusion** provides the most accurate solution by blocking traffic at the server level, working regardless of browser or device
* **Browser extensions** offer convenience by automatically working across all your Rybbit-enabled websites
* **localStorage method** gives granular control for specific websites or temporary disabling

For most users, **IP exclusion is recommended** as it provides highly accurate filtering for all devices accessing your site from the excluded IP addresses. The other methods work at the browser level and may be useful for additional flexibility or temporary exclusions.


# Identify Users (/fr/docs/identify-users)





<Callout type="warn" title="GDPR & Privacy Compliance">
  User identification involves processing personal data. Before using these features, ensure you have a lawful basis for processing (typically user consent), have disclosed tracking in your privacy policy, and provide users the ability to access and delete their data. Only collect traits you have explicit consent to process.
</Callout>

Rybbit allows you to identify logged-in users and associate their activity with a persistent identity across devices and sessions. This enables powerful user-level analytics, including tracking user journeys, understanding retention, and personalizing experiences.

<img alt="identify users" src="__img0" />

## How It Works [#how-it-works]

By default, Rybbit assigns an anonymous ID to each visitor based on their device fingerprint. When you call `identify()`, you link this anonymous visitor to a known user ID, allowing you to:

* Track the same user across multiple devices
* Associate pre-login activity with the logged-in user
* Store user metadata (traits) like email, name, and custom fields
* View identified users in your dashboard with their real names

When a new alias is created (i.e., the first time `identify()` is called for a given device), Rybbit retroactively updates all past anonymous events from that device to include the identified user ID. This means pre-login pageviews and events are attributed to the user once they identify themselves.

## Special Trait Fields [#special-trait-fields]

When identifying users, certain trait fields are treated specially by Rybbit:

| Field      | Description                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| `username` | **Primary display name** - Shown in the users list and session cards instead of the user ID |
| `name`     | **Fallback display name** - Used if username is not provided                                |
| `email`    | Displayed below the user's name in the dashboard                                            |

You can also include any custom fields you need for segmentation and analysis.

## Limits [#limits]

* **Traits size**: Maximum 2KB per identify call. Traits are stored as JSON, so keep payloads concise.
* **User ID length**: Maximum 255 characters.

## API Reference [#api-reference]

### `window.rybbit.identify(userId, traits?)` [#windowrybbitidentifyuserid-traits]

Sets a custom user ID for tracking logged-in users across devices and sessions, with optional user traits (metadata).

* `userId` (String): The unique identifier for the user. This will be stored in localStorage and persist across browser sessions. &#x2A;*Note: Custom user IDs are stored exactly as provided without any hashing or modification.**
* `traits` (Object, Optional): An object containing user metadata like email, name, username, or any custom fields. This data is stored in Rybbit and can be used to identify users in the dashboard. Setting a trait to `null` removes it from the user's profile.

```javascript
// Identify a user when they log in (without traits)
window.rybbit.identify("user_12345");

// Identify a user with traits (recommended)
window.rybbit.identify("user_12345", {
  username: "johndoe",           // Primary display name
  name: "John Doe",              // Fallback display name
  email: "john@example.com",
  plan: "premium",
  company: "Acme Inc"
});

// All subsequent events and pageviews will be associated with this user ID
```

### `window.rybbit.setTraits(traits)` [#windowrybbitsettraitstraits]

Updates the traits for the currently identified user without re-identifying them. Useful for updating user properties after initial identification.

* `traits` (Object): An object containing user metadata. New traits are merged with existing traits. &#x2A;*Setting a trait to `null` removes it from the user's profile.**

```javascript
// Update user traits after they upgrade their plan
window.rybbit.setTraits({
  plan: "enterprise",
  upgraded_at: "2024-01-15"
});

// Remove a trait by setting it to null
window.rybbit.setTraits({
  temporary_flag: null  // This trait will be removed
});
```

**Note:** You must call `identify()` before using `setTraits()`. If no user is identified, this will log a warning.

### `window.rybbit.clearUserId()` [#windowrybbitclearuserid]

Clears the stored user ID. Useful when a user logs out.

```javascript
// Clear user identification when user logs out
window.rybbit.clearUserId();
```

### `window.rybbit.getUserId()` [#windowrybbitgetuserid]

Returns the currently set user ID, or `null` if none is set.

```javascript
// Check if a user is identified
const currentUserId = window.rybbit.getUserId();
if (currentUserId) {
  console.log('Current user:', currentUserId);
} else {
  console.log('No user identified');
}
```

## Important Notes [#important-notes]

* **Unique user counts**: Every user count in the dashboard — Unique Users, the users chart, the Users table, traits, and retention — keys on the custom user ID wherever one is present, falling back to the anonymous fingerprint only for visitors who have never identified. Two people sharing an IP address and browser count as two users, and one person on a laptop and a phone counts as one. Sites that never call `identify()` are unaffected. Because the count follows the IDs you pass, sending a fresh ID per visit (rather than a stable per-person ID) will inflate it.
* **Identified sessions**: When a custom user ID is present, session assignment includes both the anonymous device fingerprint and the custom user ID. Different identified users therefore remain in separate sessions even when they share the same IP address and user agent.
* **Shared devices**: If multiple users log in from the same device (same IP address and user agent), calling `identify()` with a new user ID updates the alias to point to the new user. Future events will be attributed to the most recently identified user. Past events that were already backfilled retain their original attribution.
* **Cross-device tracking**: Identifying the same user on different devices creates separate aliases. Events from each device are linked to the user independently via the `identified_user_id` field.
* **Retroactive backfill**: The backfill runs asynchronously when a new alias is first created. ClickHouse mutations may take a short time to propagate depending on table size. Subsequent `identify()` calls from the same device (even with a different user ID) do not re-backfill old events.
* **`clearUserId()` behavior**: Calling `clearUserId()` removes the user ID from localStorage so future events are anonymous. It does not delete the alias in the database or modify previously attributed events.

## Complete Example [#complete-example]

Here's a typical workflow for user identification:

```javascript
// When user logs in
function handleLogin(userData) {
  // Set user identification with traits
  window.rybbit.identify(userData.id, {
    username: userData.username,
    name: userData.fullName,
    email: userData.email,
    plan: userData.plan
  });

  // Track login event
  window.rybbit.event("User Login", {
    method: "email"
  });
}

// When user upgrades their plan
function handlePlanUpgrade(newPlan) {
  // Update traits without re-identifying
  window.rybbit.setTraits({
    plan: newPlan,
    upgraded_at: new Date().toISOString()
  });

  // Track upgrade event
  window.rybbit.event("Plan Upgraded", {
    new_plan: newPlan
  });
}

// When user logs out
function handleLogout() {
  // Track logout event
  window.rybbit.event("User Logout");

  // Clear user identification
  window.rybbit.clearUserId();
}

// Check identification status
function checkUserStatus() {
  const userId = window.rybbit.getUserId();
  if (userId) {
    console.log("User is identified:", userId);
  } else {
    console.log("Anonymous user");
  }
}
```

**Related Documentation:**

* [Track Events](/docs/track-events)
* [Behavior Analytics - Users Tab](/docs/behavior-analytics/users)
* [API - Sending Events](/docs/api/sending-events)


# Introduction (/fr/docs)



**Rybbit** is a powerful open source web and product analytics platform. Check out our [live demo](https://demo.rybbit.com/81) using a real production site.

<DocsHomeCards />

## Getting Started [#getting-started]

Choose the option that's right for you:

* **Cloud Version:** Sign up for the [hosted version](https://app.rybbit.io/signup). Get up and running in minutes.
* **Self-Host:** Follow our [self hosting guide](/docs/self-hosting) to set up Rybbit on your own server.

And then learn how to add the [tracking script](/docs/script) to your website to start collecting data.

## Code [#code]

Rybbit is open sourced under the AGPL-3.0 license. You can find the code on [GitHub](https://github.com/rybbit-io/rybbit).

## Community [#community]

Join our [Discord server](https://discord.gg/DEhGb4hYBj) or talk to me on [X](https://x.com/yang_frog). I'm always looking for feedback and ideas to make Rybbit as awesome as possible.


# Inviting users (/fr/docs/inviting-users)





<Callout type="info">
  On self-hosted instances, this workflow is slightly different. Instead of inviting users, you can create a new user and set their password directly since self-hosted instances don't send emails.
</Callout>

<Steps>
  <Step>
    ### Add the user to your organization [#add-the-user-to-your-organization]

    Go to **Settings > Organization** and click the "Invite Member" button. Enter the user's email address.
  </Step>

  <Step>
    ### Select the user's role [#select-the-users-role]

    You can assign the user one of three roles:

    **Owners** have full access to all features including billing, organization deletion, and member management.

    **Admins** can manage members and access all sites, but cannot delete the organization or manage billing.

    **Members** can view analytics for assigned sites only. They cannot manage settings or other members.

    #### Restricting site access for members [#restricting-site-access-for-members]

    When inviting a member, you can optionally restrict their access to specific sites. Check the "Restrict access to specific sites" option and select which sites the member should be able to view.

    If you don't enable this option, the member will have access to all sites in your organization.

    <Callout type="info">
      Site access restrictions only apply to members. Admins and owners always have full access to all sites.
    </Callout>
  </Step>

  <Step>
    ### Assign teams (optional) [#assign-teams-optional]

    If your organization has [teams](/docs/teams) set up, you can assign the new member to a team during the invitation. When the member accepts the invitation, they will automatically be added to the selected team.

    This is useful for ensuring new members immediately have access to the right group of sites without needing to configure access separately.
  </Step>

  <Step>
    ### Send the invite [#send-the-invite]

    Click the "Invite" button. The user will receive an email with a link to sign up for Rybbit. You can manage all pending invitations in the Organization settings page.
  </Step>
</Steps>

## Managing site access for existing members [#managing-site-access-for-existing-members]

You can change a member's site access at any time after they've joined your organization.

1. Go to **Settings > Organization**
2. Find the member in the list and click the edit (pencil) icon in the Actions column for that member
3. Toggle "Restrict access to specific sites" and select the sites they should have access to
4. Click "Save changes"

The member will immediately only see the sites you've selected. If you disable the restriction, they'll regain access to all sites.

<Callout type="info">
  Currently, each user can only be in one organization.
</Callout>


# Localhost tracking (/fr/docs/localhost-tracking)





Rybbit does not restrict tracking to your registered domain — the tracking script works from `localhost` (or any other origin) out of the box. As long as your snippet has a valid `data-site-id`, events sent during local development are recorded like any other traffic.

```html
<script
  defer
  src="https://app.rybbit.io/api/script.js"
  data-site-id="YOUR_SITE_ID">
</script>
```

<Callout type="warning">
  Because localhost traffic is tracked by default, the usual problem is the opposite one: development visits polluting your production analytics. Use one of the approaches below to keep your data clean.
</Callout>

## Keeping development traffic out of production data [#keeping-development-traffic-out-of-production-data]

### Option 1: Use a separate development site [#option-1-use-a-separate-development-site]

Create a second site in your Rybbit dashboard (e.g. "My App (dev)") and use its site ID during development. Your production site's data stays untouched, and you can still verify events end-to-end.

```jsx
// Next.js example
export function Analytics() {
  const siteId =
    process.env.NODE_ENV === 'development'
      ? process.env.NEXT_PUBLIC_RYBBIT_DEV_SITE_ID
      : process.env.NEXT_PUBLIC_RYBBIT_SITE_ID;

  return (
    <script
      defer
      src="https://app.rybbit.io/api/script.js"
      data-site-id={siteId}
    />
  );
}
```

### Option 2: Only load the script in production [#option-2-only-load-the-script-in-production]

If you don't need analytics while developing, skip loading the script entirely outside production:

```jsx
// Next.js example
export function Analytics() {
  if (process.env.NODE_ENV !== 'production') return null;

  return (
    <script
      defer
      src="https://app.rybbit.io/api/script.js"
      data-site-id={process.env.NEXT_PUBLIC_RYBBIT_SITE_ID}
    />
  );
}
```

```javascript
// Vanilla JS example
if (process.env.NODE_ENV === 'production') {
  const script = document.createElement('script');
  script.defer = true;
  script.src = 'https://app.rybbit.io/api/script.js';
  script.setAttribute('data-site-id', 'YOUR_SITE_ID');
  document.head.appendChild(script);
}
```

### Option 3: Filter the traffic instead [#option-3-filter-the-traffic-instead]

If you want the script loaded everywhere but excluded from your stats, use your site's exclusion settings — see [Filtering Traffic](/docs/filter-traffic) and [Hiding Your Own Traffic](/docs/hiding-own-traffic).

## Troubleshooting [#troubleshooting]

**Events not showing up from localhost?**

* Confirm `data-site-id` matches the site you're looking at in the dashboard
* Check the browser console for errors and the Network tab for `POST` requests to `/api/track`
* Disable ad blockers or privacy extensions — they commonly block analytics scripts on any origin, including localhost
* Make sure the page isn't excluded by your site's IP, path, or user-agent exclusion rules


# Managing your installation (/fr/docs/managing-your-installation)





## Helpful scripts [#helpful-scripts]

<Callout>
  You probably need to run `chmod +x *.sh` before running the scripts.
</Callout>

### Updating Your Installation [#updating-your-installation]

Rybbit is updated frequently with new features and bug fixes. You can update your installation by running the following commands:

**update.sh**: Update to the latest version by pulling new code and rebuilding containers

```bash
git pull
./update.sh
```

### Restarting Your Installation [#restarting-your-installation]

**restart.sh**: Restart all services (useful when you've changed .env settings)

```bash
./restart.sh
```

## Docker Compose Commands [#docker-compose-commands]

You can also manage services directly with Docker Compose:

* **Stop all services**:
  ```bash
  docker compose stop
  ```

* **Stop and remove containers** (preserves data):
  ```bash
  docker compose down
  ```

* **Start services** (if you used setup.sh with default webserver):
  ```bash
  docker compose --profile with-webserver up -d
  ```

* **Start services** (if you used setup.sh with --no-webserver):
  ```bash
  docker compose up -d
  ```

* **View logs**:
  ```bash
  docker compose logs -f
  ```

<Callout>
  If you are using your self-hosted Rybbit without anyone else, you can disable new user signups by setting `DISABLE_SIGNUP=true` in the `.env` file at the root of the repository.
</Callout>

## Database Access [#database-access]

You can access the databases by running the following commands:

* **Access Clickhouse**:
  ```bash
  docker exec -it clickhouse clickhouse-client --database analytics
  ```

* **Access Postgres**:
  ```bash
  docker exec -it postgres psql -U frog -d analytics
  ```

### Edit Session Replay Retention Policy [#edit-session-replay-retention-policy]

The default session replay retention policy is 30 days. This may be too long for some users as session replays can take up a lot of space. You can edit it by running the following command:

```bash
docker exec -it clickhouse clickhouse-client --database analytics
ALTER TABLE session_replay_events MODIFY TTL toDateTime(timestamp) + INTERVAL 14 DAY;
ALTER TABLE session_replay_metadata MODIFY TTL start_time + INTERVAL 14 DAY;
```

## Anonymous Usage Telemetry [#anonymous-usage-telemetry]

To help us improve Rybbit, self-hosted instances automatically send anonymous usage statistics to our cloud service. This includes:

* Number of rows in a few core ClickHouse tables (events and the session replay tables)
* Total database size
* Your Rybbit version
* A hashed instance identifier

No personal data, website content, or visitor information is ever collected.

<Callout type="info">
  You can completely disable telemetry by adding `DISABLE_TELEMETRY=true` to your `.env` file and restarting your services.
</Callout>


# Organization settings (/fr/docs/organization-settings)







Access organization settings by clicking on "Organization" or going to [app.rybbit.io/settings/organization](https://app.rybbit.io/settings/organization).

<img alt="organization settings" src="__img0" />

## Organization [#organization]

### Organization Name [#organization-name]

Update your organization's display name. Only the organization owner can change this setting.

### Delete Organization [#delete-organization]

Permanently delete the organization and all associated data including sites, analytics, reports, and member associations.

<Callout type="warn">
  This action cannot be undone. You must type the organization name to confirm deletion. If you have an active subscription, you must cancel it before deleting the organization.
</Callout>

## Members [#members]

View and manage all members in your organization. The members table shows:

* **Name** - Member's display name
* **Email** - Member's email address
* **Role** - Owner, Admin, or Member
* **Site Access** - Which sites the member can access
* **Joined** - When they joined the organization

### Member Roles [#member-roles]

| Role       | Permissions                                                                               |
| ---------- | ----------------------------------------------------------------------------------------- |
| **Owner**  | Full access to all features, can manage members, billing, and delete the organization     |
| **Admin**  | Can manage members and access all sites, cannot delete the organization or manage billing |
| **Member** | Can view analytics for assigned sites only, cannot manage settings or other members       |

### Inviting Members [#inviting-members]

Owners can invite new members or create user accounts. See the [Inviting Users](/docs/inviting-users) guide for detailed instructions.

### Teams [#teams]

You can organize sites into teams to control which members have access to which sites. See the [Teams](/docs/teams) guide for details.


# Roadmap (/fr/docs/roadmap)



Rybbit is a quickly growing project. We already have quite a few features, but there is much more to come.

## Planned features [#planned-features]

* Data import from Google Analytics, PostHog, and more
* More tracking script/SDK integration guides
* Custom themes

Once again, join our [Discord server](https://discord.gg/DEhGb4hYBj) or follow me on [X](https://x.com/yang_frog) to share your feedback and ideas. We would love to hear from you!


# Troubleshooting (/fr/docs/script-troubleshooting)





If you've installed the Rybbit tracking script but aren't seeing any traffic in your dashboard, this guide will help you diagnose and fix common issues.

## Check if the Script is Loaded [#check-if-the-script-is-loaded]

The first step is to verify that the Rybbit script is properly loaded on your page.

<Steps>
  <Step>
    ### Open Your Browser's Developer Console [#open-your-browsers-developer-console]

    Right-click anywhere on your webpage and select **Inspect** (or **Inspect Element**). Then click on the **Console** tab at the top of the panel that opens.

    Alternatively, you can use keyboard shortcuts:

    * **Windows/Linux**: Press `Ctrl + Shift + J` or `F12`
    * **Mac**: Press `Cmd + Option + J`
  </Step>

  <Step>
    ### Type "rybbit" and Press Enter [#type-rybbit-and-press-enter]

    In the console, type `rybbit` and press Enter.

    **If the script is loaded correctly**, you'll see an object with functions like this:

    ```javascript
    {event: ƒ, pageview: ƒ, identify: ƒ, setTraits: ƒ, clearUserId: ƒ, …}
    ```

    **If the script is NOT loaded**, you'll see an error like:

    ```
    Uncaught ReferenceError: rybbit is not defined
    ```

    If you see the error, the script is not loading properly. Continue reading for common causes.
  </Step>
</Steps>

## Common Issues [#common-issues]

### Data Attributes Being Stripped [#data-attributes-being-stripped]

Some platforms, content management systems, tag managers, and "delay JavaScript" optimizers automatically remove or sanitize `data-*` attributes from script tags, or rebuild the tag from a `data-src` placeholder and drop everything else. If your site ID was in a `data-site-id` attribute, it gets removed and the script logs `Please provide a valid site ID`.

**Platforms known to strip attributes:**

* Google Tag Manager
* WordPress optimization plugins with "delay JavaScript" enabled (WP Rocket, Perfmatters, FlyingPress, LiteSpeed Cache)
* Some WordPress page builders
* Certain website builders (Webflow, Wix, Squarespace in some configurations)
* Some CDN or caching plugins

**Solution:** Put the site ID in the script URL instead of a data attribute. Optimizers preserve the URL:

```html
<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
```

If your platform also rewrites the `src`, inject the script from JavaScript instead:

```javascript
<script>
  (function() {
    var el = document.createElement("script");
    el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
    el.defer = true;
    document.head.appendChild(el);
  })();
</script>
```

<Callout type="info">
  For detailed Google Tag Manager setup instructions, see our [Google Tag Manager Guide](/docs/guides/google-tag-manager).
</Callout>

### Ad Blockers [#ad-blockers]

In rare cases, ad blockers may block the Rybbit tracking script. While Rybbit is privacy-focused and doesn't use cookies for tracking, some aggressive ad blockers may still flag analytics scripts.

**How to check if an ad blocker is the issue:**

1. Temporarily disable your ad blocker
2. Refresh the page
3. Check the console again for the `rybbit` object

**Solutions:**

* **For your own testing**: Disable your ad blocker or add your site to the allowlist
* **For your visitors**: Consider setting up a [proxy](/docs/proxy-guide) to serve the script from your own domain, which significantly reduces the chance of being blocked

### Script Not in the Right Location [#script-not-in-the-right-location]

The Rybbit script should be placed in the `<head>` section of your HTML. If it's placed in the wrong location or loaded after the page has already finished loading, it may not work correctly.

**Verify the script placement:**

1. View your page source (right-click → **View Page Source**)
2. Search for `rybbit` or `script.js`
3. Confirm it appears within the `<head>...</head>` tags

### Incorrect Site ID [#incorrect-site-id]

Double-check that the `siteId` in your script URL (or your `data-site-id` attribute) matches the site ID shown in your Rybbit dashboard.

1. Go to your Rybbit dashboard
2. Navigate to your site's settings
3. Copy the site ID and compare it with what's in your script tag

### Content Security Policy (CSP) Blocking [#content-security-policy-csp-blocking]

If your site has a strict Content Security Policy, it may block the Rybbit script from loading or executing.

**Check for CSP errors:**

1. Open the browser console
2. Look for errors mentioning "Content Security Policy" or "CSP"

**Solution:** Add the Rybbit script domain to your CSP headers:

```
script-src 'self' https://app.rybbit.io;
connect-src 'self' https://app.rybbit.io;
```

If you're self-hosting Rybbit, replace `app.rybbit.io` with your Rybbit instance domain.

### Script Loading Too Late in SPAs [#script-loading-too-late-in-spas]

In single-page applications (React, Vue, Next.js, etc.), if the script loads after the initial page render, the automatic pageview might not fire.

**Solution:** Ensure the script is in your root HTML template (like `index.html` or `_document.js` in Next.js), not dynamically imported in a component.

For Next.js specifically, see our [Next.js Guide](/docs/guides/nextjs).

## Testing Your Installation [#testing-your-installation]

Once you've made changes, verify that tracking is working:

1. **Check the console**: Type `rybbit` to confirm the object exists
2. **Trigger a test event**: In the console, run:
   ```javascript
   rybbit.event("test_event")
   ```
3. **Check your dashboard**: Navigate to the Events tab in your Rybbit dashboard and look for "test\_event" (it may take a few seconds to appear)
4. **Check the Network tab**: In browser dev tools, go to the Network tab, filter by "track" or "rybbit", and verify requests are being sent with 200 status codes

## Still Having Issues? [#still-having-issues]

If you've tried all the above and are still not seeing traffic:

1. **Check the browser Network tab** for any failed requests to your Rybbit instance
2. **Verify your site ID** is correct in the dashboard
3. **Check if traffic is being filtered** - review your [IP exclusions](/docs/hiding-own-traffic) and [country exclusions](/docs/filter-traffic) to ensure your traffic isn't being blocked
4. **For self-hosted instances** - ensure your Rybbit server is running and accessible

***

**Related Documentation:**

* [Tracking Script Installation](/docs/script)
* [Track Events](/docs/track-events)
* [Proxy Guide](/docs/proxy-guide)
* [Google Tag Manager Guide](/docs/guides/google-tag-manager)
* [Hide Your Own Traffic](/docs/hiding-own-traffic)
* [Filter Traffic](/docs/filter-traffic)


# Tracking script (/fr/docs/script)





To start tracking user activity on your website, add the Rybbit tracking script to your site's HTML.

## Installation [#installation]

The webpage should give you this script tag like this when you first add a website. Place it within the `<head>` section of your website. Include it on every page you wish to track.

```html
<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" async></script>
```

If you are self-hosting Rybbit `app.rybbit.io` will be domain of your Rybbit instance.

The site ID is passed in the script URL. The older `data-site-id="YOUR_SITE_ID"` attribute still works, but the URL form is recommended because script optimizers (WP Rocket, Perfmatters, FlyingPress and similar "delay JavaScript" features) rebuild script tags and drop `data-*` attributes, while leaving the URL intact.

<Callout type="info">
  **Bypass Ad Blockers**: Some ad blockers may block analytics scripts regardless of privacy compliance. To improve tracking accuracy, you can proxy the tracking script through your own domain. See our [Proxy Guide](/docs/proxy-guide) for setup instructions for Next.js, Nginx, Caddy, and more.
</Callout>

## Configuration [#configuration]

### Site Settings Configuration [#site-settings-configuration]

Most tracking options are configured through your site settings in the Rybbit dashboard. The script automatically fetches these settings when it loads:

* **Automatic Initial Pageview**: Track the first pageview when the script loads
* **SPA Navigation**: Automatically track navigation in single-page applications
* **URL Parameters**: Include or exclude query strings from tracked URLs
* **Outbound Links**: Track clicks to external websites
* **Error Tracking**: Capture JavaScript errors and unhandled promise rejections
* **Session Replay**: Record user interactions for debugging and UX analysis
* **Web Vitals**: Collect Core Web Vitals performance metrics

### Script Attributes [#script-attributes]

These are the attributes you can pass to the script tag.

| Attribute            | Type     | Default | Description                                                                                                                                                                                                                                                                        |
| :------------------- | :------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-skip-patterns` | `string` | `[]`    | A JSON string array of URL path patterns to ignore. Pageviews matching these patterns won't be tracked. Supports two types of wildcards: `*` (matches within a segment) and `**` (matches across segments), plus regex patterns prefixed with `re:`.                               |
| `data-mask-patterns` | `string` | `[]`    | A JSON string array of URL path patterns to mask for privacy. Pageviews matching these patterns will be tracked, but the actual URL path will be replaced with the pattern itself in analytics data. Supports the same wildcards and `re:` regex patterns as `data-skip-patterns`. |
| `data-debounce`      | `string` | `"500"` | The delay (in milliseconds) before tracking a pageview after URL changes via the History API (`pushState`, `replaceState`). Set to `0` to disable debouncing.                                                                                                                      |
| `data-tag`           | `string` | `""`    | A label applied to all events from this script instance. Useful for A/B testing, deploy versioning, or cohort segmentation. Max 256 characters. See [Tagging](/docs/tagging).                                                                                                      |

{/* ### Feature Flags

  The tracking script automatically evaluates client and both-runtime feature flags when it loads. Read evaluated flags from `window.rybbit` after the script is ready:

  ```javascript
  window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);
  const config = rybbit.flagPayload("checkout_config", {});
  });
  ```

  Available methods:

  | Method | Description |
  | --- | --- |
  | `flag(key, fallback)` | Returns a boolean, variant key, or fallback value. Also records a feature flag exposure once per flag value/version. |
  | `flagPayload(key, fallback)` | Returns the payload for a flag, variant, or remote config. |
  | `flags()` | Returns all evaluated flag values. |
  | `flagPayloads()` | Returns all available flag payloads. |

  See [Feature Flags](/docs/feature-flags) for targeting rules, remote config, and server-side evaluation. */}

### Session Replay Attributes [#session-replay-attributes]

These attributes configure rrweb session replay behavior. They only apply when session replay is enabled in your site settings.

| Attribute                         | Type          | Default                          | Description                                                                                                                   |
| :-------------------------------- | :------------ | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `data-replay-mask-text-selectors` | `string`      | `[]`                             | A JSON string array of CSS selectors for elements whose text content should be masked. Example: `'[".user-name", "#email"]'`. |
| `data-replay-block-class`         | `string`      | `"rr-block"`                     | CSS class name for elements to exclude entirely from recording. Elements with this class won't appear in replays.             |
| `data-replay-block-selector`      | `string`      | `null`                           | CSS selector for elements to exclude from recording. Example: `".sensitive-content, #private-section"`.                       |
| `data-replay-ignore-class`        | `string`      | `"rr-ignore"`                    | CSS class name for elements whose input events should be ignored. The element appears but interactions aren't recorded.       |
| `data-replay-ignore-selector`     | `string`      | `null`                           | CSS selector for elements whose input events should be ignored. Example: `"input[name='credit-card']"`.                       |
| `data-replay-mask-text-class`     | `string`      | `"rr-mask"`                      | CSS class name for elements whose text content should be masked (shown as asterisks).                                         |
| `data-replay-mask-all-inputs`     | `boolean`     | `true`                           | When true, all input values are masked as asterisks for privacy. Set to `"false"` to disable.                                 |
| `data-replay-mask-input-options`  | `JSON object` | `{"password":true,"email":true}` | Specify which input types to mask. Example: `'{"password":true,"email":true,"tel":true}'`.                                    |
| `data-replay-collect-fonts`       | `boolean`     | `true`                           | When true, website fonts are collected for accurate replay rendering. Set to `"false"` to reduce data size.                   |
| `data-replay-sampling`            | `JSON object` | See below                        | Configure event sampling to reduce data volume. See sampling options below.                                                   |
| `data-replay-slim-dom-options`    | `JSON object` | See below                        | Configure which DOM elements to exclude from recording. See slimDOM options below.                                            |

### Pattern Matching Details [#pattern-matching-details]

For `data-skip-patterns` and `data-mask-patterns`, two types of wildcards are supported:

* `*` - Matches any characters within a single path segment (doesn't match across `/`)
* `**` - Matches any characters across multiple path segments (includes `/`)

Examples:

* `/admin/*` matches `/admin/dashboard` but not `/admin/users/list`
* `/admin/**` matches both `/admin/dashboard` and `/admin/users/list`
* `/blog/*/comments` matches `/blog/post-123/comments` but not `/blog/category/post/comments`

Regex patterns are also supported when prefixed with `re:`. The regex is used as-is, so add `^` and `$` if you want a full-path match.

Examples:

* `re:^/users/\\d+$` matches `/users/123` but not `/users/abc`
* `re:^/private/.*$` matches anything under `/private/`

Example usage:

```html
data-skip-patterns='["/admin/**", "/blog/drafts/*", "/preview/**"]'
data-mask-patterns='["/users/*/settings", "/accounts/**", "/orders/*/details"]'
```

Regex usage:

```html
data-skip-patterns='["re:^/private/.*$"]'
data-mask-patterns='["re:^/users/\\d+/settings$"]'
```

**Example with debugging overrides:**

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="456"
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-debounce="300"
></script>
```

## Session Replay Configuration [#session-replay-configuration]

When session replay is enabled in your site settings, you can fine-tune the recording behavior using the attributes above. This section covers the more complex configuration options.

### Privacy Controls [#privacy-controls]

Protect sensitive user information using these options:

| Option                 | Best For                                                           |
| ---------------------- | ------------------------------------------------------------------ |
| `data-replay-block-*`  | Completely hide elements (e.g., admin panels, modals with PII)     |
| `data-replay-ignore-*` | Show elements but don't record interactions (e.g., form fields)    |
| `data-replay-mask-*`   | Show element structure but hide text content (e.g., names, emails) |

**Example - Comprehensive privacy setup:**

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="123"
  data-replay-block-selector=".admin-panel, #payment-modal"
  data-replay-ignore-selector="input[name='ssn'], input[name='credit-card']"
  data-replay-mask-text-selectors='[".user-name", "#email", "[data-pii]"]'
  data-replay-mask-input-options='{"password":true,"email":true,"tel":true}'
></script>
```

### Sampling Configuration [#sampling-configuration]

The `data-replay-sampling` attribute controls how frequently events are recorded. Lower sampling rates reduce data volume but may miss some interactions.

**Default sampling configuration:**

```json
{
  "mousemove": false,
  "mouseInteraction": {
    "MouseUp": false,
    "MouseDown": false,
    "Click": true,
    "ContextMenu": false,
    "DblClick": true,
    "Focus": true,
    "Blur": true,
    "TouchStart": false,
    "TouchEnd": false
  },
  "scroll": 500,
  "input": "last",
  "media": 800
}
```

**Sampling options:**

* `mousemove`: `false` to disable, or number (ms) for sampling interval
* `scroll`: Sampling interval in milliseconds (e.g., `500` = sample every 500ms)
* `input`: `"last"` to only record final value, or `"all"` to record every keystroke
* `media`: Sampling interval for media events in milliseconds

**Example - Enable mouse tracking for UX analysis:**

```html
data-replay-sampling='{"mousemove":100,"scroll":150}'
```

### SlimDOM Options [#slimdom-options]

The `data-replay-slim-dom-options` attribute controls which DOM elements are excluded from recording to reduce data size.

**Default slimDOM configuration:**

```json
{
  "script": false,
  "comment": true,
  "headFavicon": true,
  "headWhitespace": true,
  "headMetaDescKeywords": true,
  "headMetaSocial": true,
  "headMetaRobots": true,
  "headMetaHttpEquiv": true,
  "headMetaAuthorship": true,
  "headMetaVerification": true
}
```

Set to `true` to enable all slimDOM options, or `false` to disable all:

```html
data-replay-slim-dom-options="true"
```

### Complete Example [#complete-example]

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="456"
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-debounce="300"
  data-replay-block-selector=".sensitive-content"
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-replay-mask-all-inputs="true"
  data-replay-collect-fonts="false"
  data-replay-sampling='{"mousemove":false,"scroll":500}'
></script>
```


# Segments (/fr/docs/segments)





A segment is a named, reusable set of [filters](/docs/feature-guides/main-tab#filters). Instead of rebuilding "mobile visitors from Germany who came from search" every time, save it once and apply it to the main dashboard, pages, sessions, funnels, journeys, retention, and exports with one click.

Segments live inside the **Filter** button. Nothing else changes in the dashboard: applying a segment expands its filters into the same filter bar every report already reads.

## Creating a segment [#creating-a-segment]

Open the **Filter** button and switch to the **Segments** tab. There are two ways to create one:

<Steps>
  <Step>
    ### From scratch [#from-scratch]

    Click **New segment**. The dialog has its own filter editor, so you can build the definition without applying anything to the dashboard first.
  </Step>

  <Step>
    ### From the current filters [#from-the-current-filters]

    Once the dashboard has filters applied, the Segments tab offers **Save current filters as segment**. The dialog opens with those filters and a suggested name.
  </Step>
</Steps>

Every segment has:

* **Name** — what the group means to you, such as "Paid traffic" or "Logged-in users"
* **Filters** — at least one. Every filter must match; multiple values inside one filter are alternatives
* **Available on** — this site only, or every site in the organization (organization-wide segments can only be created by admins and owners)
* **Description** — optional notes for your team
* **Show on the public dashboard and private links** — off by default

<Callout type="info">
  Filters in a segment are validated against the same schema as the filter bar, so a segment can never save something the dashboard could not query.
</Callout>

## Applying a segment [#applying-a-segment]

In the **Segments*&#x2A; tab, click a segment to apply it. It appears in the filter bar as a single chip named after the segment. Click the chip to see the filters it contains; click the &#x2A;*×** to remove all of them at once.

Ad-hoc filters work alongside an applied segment. Add a filter the usual way and it is ANDed with the segment. If one of the segment's own filters is changed on the dashboard, the chip reads &#x2A;*(edited)** so you know the row no longer matches the saved definition; the segment itself is unchanged.

Segments are part of the URL, so a dashboard link with a segment applied opens the same view for whoever you share it with.

## Editing and deleting [#editing-and-deleting]

Use the &#x2A;*⋯** menu on a segment in the Segments tab, or **Edit segment** from the applied chip. Changes apply everywhere the segment is used. Deleting a segment removes it for everyone; links that already expanded its filters keep working.

## Permissions [#permissions]

| Role                                    | Read and apply                                   | Create                     | Edit and delete       |
| --------------------------------------- | ------------------------------------------------ | -------------------------- | --------------------- |
| Owner or admin                          | All segments                                     | Site and organization-wide | Any segment           |
| Member                                  | All segments                                     | Site segments              | Segments they created |
| Public dashboard or private-link viewer | Segments marked as shown on the public dashboard | —                          | —                     |

## API and MCP [#api-and-mcp]

Every analytics endpoint accepts a `segment_id` query parameter that is expanded server-side, ANDed with any `filters` you also pass. Segments themselves are managed through the [Segments endpoints](/docs/api/segments/list). The [MCP server](/docs/mcp) exposes `list_segments` and `apply_segment`.


# Self-hosted vs Cloud (/fr/docs/self-host-vs-cloud)





Rybbit offers two deployment options: a fully-managed [cloud version](https://rybbit.com) and a [self-hosted](/docs/self-hosting) solution. This guide will help you choose the right option for your needs.

## Quick Comparison [#quick-comparison]

| Feature                               | Cloud                                                                                                                             | Self-Hosted                                                                                                                                          |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup Time**                        | Minutes                                                                                                                           | 30 - 120 minutes                                                                                                                                     |
| **Maintenance Required**              | None                                                                                                                              | Regular updates                                                                                                                                      |
| **Cookieless & Privacy friendly**     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Web Analytics**                     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **API**                               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Globe**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Session Replays**                   | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth="3" /> (On pro tier)</span> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Funnels**                           | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Goals**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Sessions**                          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Journeys**                          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Users**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Retention**                         | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Error tracking**                    | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Organizations/Teams**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Pages View**                        | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />                                                                                    |
| **Web Vitals**                        | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Email reports**                     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />                                                                                    |
| **Google Search Console integration** | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth="3" /> (Requires Google OAuth env vars)</span> |


# Quick start (/fr/docs/self-hosting)





This guide will walk you through setting up your own instance of Rybbit using our setup script. If you want to manually setup Rybbit using the Docker Compose file, check out our [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) guide.

## Prerequisites [#prerequisites]

Before you begin, ensure you have the following:

* **A VPS:** Try to get one with at least 2GB of RAM.
* **A Domain Name:** You'll need a domain or subdomain (e.g., `tracking.yourdomain.com`) pointed to your VPS's IP address. HTTPS is required because browsers block tracking scripts served over insecure HTTP.

<Callout type="info">
  This guide has been tested on Ubuntu 24 LTS (x86\_64). If your server is ARM, it must be at least ARMv8.2-A for Clickhouse support.
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Point Your Domain to Your VPS [#point-your-domain-to-your-vps]

    Configure your domain's DNS settings to point to your VPS's public IP address. This usually involves:

    1. Finding your VPS's public IPv4 address (from your hosting provider, e.g., Hetzner).
    2. Logging into your domain registrar or DNS provider (e.g., GoDaddy, Namecheap, Cloudflare).
    3. Adding an `A` record:
       * **Host/Name:** Your desired subdomain (e.g., `tracking`) or `@` for the root domain.
       * **Value:** Your VPS's IPv4 address.
       * **Proxy Status:** When using Cloudflare, either:
         * Set to "DNS only" (recommended for most setups)
         * Or if keeping the proxy enabled, set SSL/TLS encryption mode to "Full" or "Full (strict)" in your Cloudflare dashboard under SSL/TLS settings

    <Callout type="warning">
      If you keep Cloudflare's proxy enabled and your domain has other services not running on HTTPS, using Full or Full (strict) mode might cause issues with those services. In such cases, either use "DNS only" mode or ensure all your services support HTTPS.
    </Callout>

    DNS changes might take some time to propagate globally. Use [DNS Checker](https://dnschecker.org/) to verify.
  </Step>

  <Step>
    ### Install Docker Engine [#install-docker-engine]

    Connect to your VPS via SSH.

    Follow the official Docker Engine installation instructions for your Linux distribution:
    [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
  </Step>

  <Step>
    ### Clone the Rybbit Repository [#clone-the-rybbit-repository]

    Clone the project repository from GitHub (Git is usually pre-installed on most server distributions):

    ```bash
    git clone https://github.com/rybbit-io/rybbit.git
    cd rybbit
    ```
  </Step>

  <Step>
    ### Run the Setup Script [#run-the-setup-script]

    The repository includes a setup script that configures the necessary environment variables (including generating a secure secret) and starts the application using Docker Compose.

    <Callout type="warning">
      Important: Make all scripts executable before proceeding!

      ```bash
      chmod +x *.sh
      ```
    </Callout>

    Run the setup script, replacing `your.domain.name` with the domain or subdomain you configured in the prerequisites:

    ```bash
    ./setup.sh your.domain.name
    ```

    If you want to enable 3D map visualizations, you can add the `--mapbox-token` flag:

    ```bash
    ./setup.sh your.domain.name --mapbox-token YOUR_MAPBOX_TOKEN
    ```

    The script will create a `.env` file and then build and start the containers. This might take a few minutes the first time.

    <Callout type="info">
      By default, we assume you are on a blank VPS and automatically setup a Caddy webserver. If you want to use your own webserver or need more control over the setup, check out:

      * [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) - For users with existing reverse proxies or deployment tools
      * [Advanced Self-Hosting Guide](/docs/self-hosting-guides/self-hosting-advanced) - For custom configurations and Nginx setup
    </Callout>
  </Step>

  <Step>
    ### Sign Up [#sign-up]

    Once the services are running and DNS has propagated, Caddy (the webserver) will automatically obtain an SSL certificate for your domain.

    Open your browser and navigate to `https://your.domain.name/signup` (using the domain you provided to the setup script).

    Create your admin account. You can then log in and start adding your websites!
  </Step>
</Steps>

If you run into any issues or need help, feel free to join our Discord community!


# Site settings (/fr/docs/site-settings)







Access your site settings by clicking the settings icon in your site's Rybbit dashboard.

<img alt="site settings" src="__img0" />

## Privacy & Security [#privacy--security]

### Public Analytics [#public-analytics]

Make your analytics publicly accessible by enabling the "Public Analytics" toggle.

* External viewers have read-only access to your analytics data
* Viewers cannot edit settings, reports, funnels, or goals
* Your other websites are not affected

### User ID Salting [#user-id-salting]

Rybbit stores user IDs as a hashed combination of IP + user agent. This allows identifying users across sessions, but may be considered storing personally identifiable data under GDPR.

Enable "User ID Salting" to have Rybbit forget about unique users every day. If a user visits 10 times in one day, they count as one user with 10 sessions. But if they visit once a day for 10 days, they appear as a new user each day.

**Downsides of enabling user ID salting:**

* User session history beyond 24 hours is not available
* Unique user counts over periods longer than 24 hours will be inflated
* The user retention page becomes effectively useless

### Block Bot Traffic [#block-bot-traffic]

Enable "Block Bot Traffic" to prevent detected bot traffic from being tracked in your normal analytics. See [Bot detection](/docs/bot-detection) for how Rybbit identifies and stores bot traffic.

### Track IP Address [#track-ip-address]

Enable "Track IP Address" to store the IP address of visitors.

<Callout type="warn">
  This is not GDPR compliant. Only enable if you have a legitimate need and proper consent mechanisms in place.
</Callout>

## Analytics Features [#analytics-features]

### Session Replay <span className="text-green-500 text-sm">(Pro)</span> [#session-replay-pro]

Record and replay user sessions to understand user behavior. This feature allows you to see exactly how users interact with your site.

### Web Vitals <span className="text-green-500 text-sm">(Standard)</span> [#web-vitals-standard]

Track Core Web Vitals metrics including:

* **LCP** (Largest Contentful Paint)
* **CLS** (Cumulative Layout Shift)
* **INP** (Interaction to Next Paint)
* **FCP** (First Contentful Paint)
* **TTFB** (Time to First Byte)

### Error Tracking <span className="text-green-500 text-sm">(Standard)</span> [#error-tracking-standard]

Capture JavaScript errors and exceptions from your site to identify and fix issues affecting your users.

### Track Outbound Links [#track-outbound-links]

Track when users click on external links leaving your site. Enabled by default.

### Track URL Parameters [#track-url-parameters]

Include query string parameters in page tracking. Enabled by default. Disable if you want cleaner URLs in your analytics or need to exclude sensitive parameters.

### Track Initial Page View [#track-initial-page-view]

Automatically track the first page view when the tracking script loads. Enabled by default.

### Track SPA Navigation [#track-spa-navigation]

Automatically track navigation in single-page applications (SPAs). Enabled by default. This detects URL changes via the History API and tracks them as page views.

## Traffic Filtering [#traffic-filtering]

### IP Exclusions [#ip-exclusions]

Block specific IP addresses or ranges from being tracked. Supports:

* Individual IP addresses (e.g., `192.168.1.1`)
* CIDR notation (e.g., `192.168.1.0/24`)
* IPv4 ranges (e.g., `192.168.1.1-192.168.1.255`)

### Country Exclusions [#country-exclusions]

Block all traffic from specific countries using ISO country codes (e.g., `US`, `DE`, `FR`).

### Path Exclusions [#path-exclusions]

Exclude traffic to specific pages. Use `*` as a wildcard (e.g., `/admin/*` or `/preview`). Matching is case-insensitive. Up to 100 path exclusions are allowed.

### Hostname Exclusions [#hostname-exclusions]

Exclude traffic from specific hostnames such as staging or preview domains. Use `*` as a wildcard (e.g., `localhost` or `*.vercel.app`). Matching is case-insensitive. Up to 100 hostname exclusions are allowed.

### User Agent Exclusions [#user-agent-exclusions]

Exclude traffic from user agents containing any of these terms. Matching is a case-insensitive substring (e.g., `HeadlessChrome`). Up to 100 user agent exclusions are allowed.

All of these exclusions work at the server level, ensuring blocked traffic never reaches your analytics database.

## Embeds [#embeds]

Show Rybbit data on another site with an embeddable iframe.

* **Widget Embeds** show a compact live visitor widget. Enable them from the **Widget Embeds** tab. This is independent of Public Analytics and only exposes the data the widget displays. See the [Widget Embeds guide](/docs/embeds/widget) for details.
* **Dashboard Embed** shows the analytics dashboard in an iframe. Configure it from the **Dashboard Embed** tab. It uses a generated private link, not Public Analytics. See the [Dashboard Embed guide](/docs/embeds/dashboard) for details.

## Google Search Console <span className="text-green-500 text-sm">(Cloud)</span> [#google-search-console-cloud]

Connect your Google Search Console account to see search performance data alongside your analytics.

## Change Domain [#change-domain]

Update the domain for your site. Changing domains does not affect existing data - all historical analytics are preserved.

## Delete Site [#delete-site]

Permanently delete a site and all associated data.

<Callout type="warn">
  This action cannot be undone. All analytics data, reports, funnels, and goals will be permanently deleted.
</Callout>


# Tagging (/fr/docs/tagging)



Tags let you label all events from a script instance with a string identifier. This is useful for A/B testing, deploy labeling, cohort segmentation, and any scenario where you want to slice your analytics by a custom dimension that applies to the entire page.

If you need Rybbit to choose a value at runtime, gradually roll out a feature, or serve remote config, use [Feature Flags](/docs/feature-flags) instead.

## How It Works [#how-it-works]

Add a `data-tag` attribute to your Rybbit script tag. Every event (pageviews, custom events, outbound clicks, etc.) sent from that page will include the tag value, which is stored in ClickHouse and available as a filter in the dashboard.

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="YOUR_SITE_ID"
  data-tag="variant-a"
></script>
```

The tag is a simple string with a maximum length of 256 characters. If `data-tag` is not set or is empty, no tag is stored.

## Use Cases [#use-cases]

### A/B Testing [#ab-testing]

Serve different script tags to different user groups and compare behavior:

```html
<!-- Variant A -->
<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-a"></script>

<!-- Variant B -->
<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-b"></script>
```

Then filter by tag in the dashboard to compare metrics between variants.

### Deploy / Release Labeling [#deploy--release-labeling]

Tag events with the current deploy version to correlate releases with changes in user behavior or errors:

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="1"
  data-tag="v2.4.1"
></script>
```

### Cohort Segmentation [#cohort-segmentation]

Label traffic from different sources, campaigns, or user segments:

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="1"
  data-tag="beta-users"
></script>
```

## Filtering by Tag [#filtering-by-tag]

Once events with tags are flowing in, you can filter by tag anywhere in the dashboard:

1. Click the **filter** button in the dashboard header
2. Select **Tag** from the filter parameter dropdown
3. Choose an operator (is, is not, contains, etc.)
4. Enter the tag value

The tag filter works on all dashboard pages including overview, pages, referrers, events, users, funnels, and goals.

## API Usage [#api-usage]

When sending events via the [HTTP API](/docs/api/sending-events), include `tag` in the request body:

```json
{
  "site_id": "YOUR_SITE_ID",
  "type": "pageview",
  "hostname": "example.com",
  "pathname": "/",
  "tag": "variant-a"
}
```

## Important Notes [#important-notes]

* Each script instance can only have one tag. If you need multiple dimensions, consider using [custom event properties](/docs/track-events) instead.
* Tags are set at the script level, not per-event. All events from a page load share the same tag.
* The tag value is stored as-is (no hashing or transformation).
* Empty or missing `data-tag` attributes result in no tag being stored.

**Related Documentation:**

* [Tracking Script](/docs/script)
* [Track Events](/docs/track-events)
* [Identify Users](/docs/identify-users)


# Teams (/fr/docs/teams)







Teams let you group sites together and control which organization members can access them. This is useful for organizations managing multiple properties where different people are responsible for different sites.

Access teams by clicking on "Teams" or going to [app.rybbit.io/settings/teams](https://app.rybbit.io/settings/teams).

<img alt="teams" src="__img0" />

## How Teams Work [#how-teams-work]

A team has three things:

* **A name** — identifies the team (e.g. "Marketing Sites", "Client Projects")
* **Members** — organization members assigned to the team
* **Sites** — the sites that belong to the team

When a member is assigned to a team, they can access all sites within that team. Admins and owners always have access to all sites regardless of team assignments.

<Callout type="info">
  Teams are an organizational tool for admins and owners. Members with the "Member" role can only see sites that belong to their assigned teams (unless they have unrestricted access).
</Callout>

## Creating a Team [#creating-a-team]

1. Go to **Settings > Teams**
2. Click the **Create Team** button
3. Enter a team name
4. Select which members should belong to the team
5. Select which sites the team should have access to
6. Click **Create Team**

You can also create a team directly from the team filter on the home page.

## Managing Teams [#managing-teams]

### Editing a Team [#editing-a-team]

Click the edit icon on any team card to update its name, members, or site assignments.

### Deleting a Team [#deleting-a-team]

Click the delete icon on a team card. Sites assigned to the team will become unassigned and visible to all members.

<Callout type="warn">
  Deleting a team removes all member-to-site associations through that team. Members who only had access via the deleted team will lose access to those sites.
</Callout>

## Filtering by Team [#filtering-by-team]

On the home page, use the team selector in the toolbar to filter the site list by team. The options are:

* **All Teams** — show all sites
* **No Team** — show only sites not assigned to any team
* **Specific team** — show only sites belonging to that team

## Assigning Teams During Invitation [#assigning-teams-during-invitation]

When [inviting a new member](/docs/inviting-users), you can optionally assign them to a team. When the member accepts the invitation, they will automatically be added to the selected team.

## Permissions [#permissions]

| Role       | Can create teams | Can edit/delete teams | Can view team-restricted sites     |
| ---------- | ---------------- | --------------------- | ---------------------------------- |
| **Owner**  | Yes              | Yes                   | All sites                          |
| **Admin**  | Yes              | Yes                   | All sites                          |
| **Member** | No               | No                    | Only sites in their assigned teams |


# Track Events (/fr/docs/track-events)



The script exposes a global object `window.rybbit` with functions for manual tracking of events, as well as the ability to track events using data attributes on HTML elements.

## Using Data Attributes [#using-data-attributes]

You can track custom events by adding data attributes to any HTML element:

```html
<!-- Basic event tracking -->
<button data-rybbit-event="signup_clicked">Sign Up</button>

<!-- Event with custom properties -->
<button
  data-rybbit-event="purchase_click"
  data-rybbit-prop-product="premium"
  data-rybbit-prop-price="49.99"
>
  Buy Now
</button>
```

This approach requires no JavaScript and works on any clickable element.

## Available Functions [#available-functions]

### `window.rybbit.event(eventName, properties)` [#windowrybbiteventeventname-properties]

Tracks a custom event with optional properties.

* `eventName` (String): The name of the custom event (max 256 characters).
* `properties` (Object, Optional): An object containing custom data (max 2KB characters). Only strings numbers are supported as values.

```javascript
// Track a simple custom event
window.rybbit.event("Signup Button Clicked");

// Track a custom event with properties
window.rybbit.event("Item Added To Cart", {
  itemId: "PROD123",
  price: 49.99,
  category: "Clothing"
});
```

### `window.rybbit.pageview()` [#windowrybbitpageview]

Tracks a pageview. Useful when automatic SPA navigation tracking is disabled in your site settings, or when you need to manually trigger a pageview.

```javascript
// Track a pageview
window.rybbit.pageview();
```

## TypeScript Support [#typescript-support]

Put this as `rybbit.d.ts` anywhere in your project to avoid having to do `(window as any).rybbit.event()` everywhere.

```typescript
interface Rybbit {
    /**
     * Tracks a page view
     */
    pageview: () => void;

    /**
     * Tracks a custom event
     * @param name Name of the event
     * @param properties Optional properties for the event
     */
    event: (name: string, properties?: Record<string, any>) => void;

    /**
     * Sets a custom user ID for tracking logged-in users
     * @param userId The user ID to set (will be stored in localStorage)
     * @param traits Optional user metadata (email, name, custom fields)
     */
    identify: (userId: string, traits?: Record<string, unknown>) => void;

    /**
     * Updates traits for the currently identified user
     * @param traits User metadata to merge with existing traits
     */
    setTraits: (traits: Record<string, unknown>) => void;

    /**
     * Clears the stored user ID
     */
    clearUserId: () => void;

    /**
     * Gets the currently set user ID
     * @returns The current user ID or null if not set
     */
    getUserId: () => string | null;

    /**
     * Manually tracks outbound link clicks
     * @param url The URL of the outbound link
     * @param text Optional text content of the link
     * @param target Optional target attribute of the link
     */
    trackOutbound: (url: string, text?: string, target?: string) => void;

    /**
     * Evaluates a feature flag and returns its value. Reading a flag records a
     * feature flag exposure once per flag value/version.
     * @param key The flag key
     * @param fallback Value returned before flags resolve or if the flag is inactive
     */
    flag: <T = unknown>(key: string, fallback?: T) => T;

    /**
     * Returns the payload for a feature flag or its selected variant.
     * Use this for remote config and multivariate payloads.
     * @param key The flag key
     * @param fallback Value returned before flags resolve or if the flag is inactive
     */
    flagPayload: <T = unknown>(key: string, fallback?: T) => T;

    /**
     * Returns all evaluated flag values keyed by flag key
     */
    flags: () => Record<string, unknown>;

    /**
     * Returns all available flag payloads keyed by flag key
     */
    flagPayloads: () => Record<string, unknown>;

    /**
     * Runs a callback once the tracking script and feature flags are ready.
     * Use this before reading flags during page initialization.
     * @param callback Receives the ready rybbit instance
     */
    onReady: (callback: (rybbit: Rybbit) => void) => void;
}

declare global {
    interface Window {
        rybbit: Rybbit;
    }
}

export {};
```

## Server-Side Tracking [#server-side-tracking]

For tracking events from server-side applications, mobile apps, or any platform outside the browser, you can use the HTTP API. This is useful for:

* Server-side event tracking (Node.js, Python, Go, etc.)
* Mobile app analytics (iOS, Android, Flutter)
* Backend integrations and webhooks
* Scenarios where the JavaScript snippet can't be used

See the [API documentation](/docs/api/sending-events) for detailed examples in multiple languages including authentication, parameters, and rate limiting information.

***

**Related Documentation:**

* [Identify Users](/docs/identify-users)
* [Behavior Analytics - Events Tab](/docs/behavior-analytics/events)
* [Behavior Analytics - Users Tab](/docs/behavior-analytics/users)
* [Behavior Analytics - Sessions Tab](/docs/behavior-analytics/sessions)
* [Product Analytics - Retention Guide](/docs/product-analytics/retention_guide)
* [Product Analytics - Funnels](/docs/product-analytics/funnels_guide)
* [API - Sending Events](/docs/api/sending-events)
* [Blog: Churn Rate vs Retention Rate](/blog/churn-rate-vs-retention-rate)
* [Web SDK Reference](/docs/sdks/web)


# Troubleshooting (/fr/docs/troubleshooting)





## Full Docker Cleanup [#full-docker-cleanup]

If you encounter issues with Docker containers, images, or volumes and need to start fresh, you can perform a complete Docker cleanup. This will remove all containers, images, volumes, and custom networks.

<Callout type="warn">
  **Warning**: This will remove ALL Docker containers, images, and volumes on your system, not just Rybbit-related ones. Make sure you don't have other important Docker containers running.
</Callout>

### Steps for Complete Docker Cleanup [#steps-for-complete-docker-cleanup]

<Steps>
  <Step>
    ### Remove your environment file [#remove-your-environment-file]

    ```bash
    rm .env
    ```
  </Step>

  <Step>
    ### Stop all running containers: [#stop-all-running-containers]

    ```bash
    docker stop $(docker ps -q)
    ```
  </Step>

  <Step>
    ### Remove all containers (both running and stopped): [#remove-all-containers-both-running-and-stopped]

    ```bash
    docker rm -f $(docker ps -aq)
    ```
  </Step>

  <Step>
    ### Remove all images: [#remove-all-images]

    ```bash
    docker rmi -f $(docker images -q)
    ```
  </Step>

  <Step>
    ### Remove all volumes: [#remove-all-volumes]

    ```bash
    docker volume rm -f $(docker volume ls -q)
    ```
  </Step>

  <Step>
    ### Remove all custom networks (preserves default networks): [#remove-all-custom-networks-preserves-default-networks]

    ```bash
    docker network rm $(docker network ls | grep -v "bridge\|host\|none" | awk '{print $1}')
    ```
  </Step>
</Steps>

### Alternative: Rybbit-Specific Cleanup [#alternative-rybbit-specific-cleanup]

If you only want to clean up Rybbit-related Docker resources without affecting other containers, use these commands instead:

```bash
# Stop and remove Rybbit containers
docker-compose down

# Remove Rybbit images
docker-compose down --rmi all

# Remove Rybbit volumes (this will delete your data!)
docker-compose down --volumes

# Complete Rybbit cleanup
docker-compose down --rmi all --volumes --remove-orphans
```

### After Cleanup [#after-cleanup]

Once you've completed the cleanup, you can restart Rybbit by following the setup instructions:

```bash
# Copy environment file
cp .env.example .env

# Edit .env with your configuration
# Then start the services
docker-compose up -d
```

## ClickHouse keeps crashing on a Proxmox VM [#clickhouse-keeps-crashing-on-a-proxmox-vm]

ClickHouse requires the SSE 4.2 instruction set. Proxmox VMs default to a generic CPU type (like `kvm64` or `x86-64-v2-AES`) that doesn't expose all of the host CPU's instruction sets to the VM, which causes ClickHouse to fail with `Illegal instruction` errors or get stuck in a restart loop.

To fix this, set the VM's CPU type to `host` so it passes through the physical CPU directly:

<Steps>
  <Step>
    ### Open the VM's hardware settings [#open-the-vms-hardware-settings]

    In the Proxmox web UI, select your VM, then go to **Hardware** → **Processors** → **Edit**.
  </Step>

  <Step>
    ### Set the CPU type to `host` [#set-the-cpu-type-to-host]

    Change the **Type** dropdown to `host` and click **OK**.
  </Step>

  <Step>
    ### Fully stop and start the VM [#fully-stop-and-start-the-vm]

    A reboot from inside the guest is not enough — do a full **Stop** and then **Start** from Proxmox for the CPU change to take effect.
  </Step>
</Steps>

<Callout type="info">
  The `host` CPU type can prevent live migration between Proxmox nodes with different CPU models. If you need migration, any CPU type that includes SSE 4.2 (e.g. `x86-64-v2-AES` on a host that supports it, or newer) may also work — but `host` is the most reliable option.
</Callout>

## I ran out of disk space [#i-ran-out-of-disk-space]

Regular web analytics events take up almost no space in Clickhouse, so it is very unlikely that you ran out of disk space from from this. There are two main reasons why you might have run out of disk space:

### 1. You are using session replay [#1-you-are-using-session-replay]

On self-hosted instances where we don't have access to S3 compatible object storage, session replays are stored in Clickhouse. Each session replay is at least 1000x the data footprint of the web analytics events. So it's very easy to run out of disk space.

We have a 30 day retention policy for session replays events, so if you turn off session replay, your disk space will slowly come back. If you need to immediately free up space, you can truncate the session replays table:

```bash
docker exec -it clickhouse clickhouse-client --database analytics

TRUNCATE TABLE session_replay_events;
TRUNCATE TABLE session_replay_metadata;
```

### 2. You didn't mount the Clickhouse log suppression configs [#2-you-didnt-mount-the-clickhouse-log-suppression-configs]

In our [docker-compose.yml](https://github.com/rybbit-io/rybbit/blob/master/docker-compose.yml), we have a config for Clickhouse that suppresses logs. Clickhouse stores a ton of logs in the log tables by default. This will quickly fill up your disk space if left unchecked.

If you follow the standard installation process, the configs are already mounted for you. If you rolled your own Docker setup, you need to mount the configs manually.


# Migration to v1.0 (/fr/docs/v1-migration)





This guide covers the breaking changes and migration steps when upgrading to Rybbit v1.0.

## API Path Changes [#api-path-changes]

In v1.0, we've simplified the reverse proxy configuration by having the backend expect requests with the `/api/` prefix. This eliminates the need for custom path rewriting in reverse proxy configurations.

### If You're Using the Built-in Caddy Server [#if-youre-using-the-built-in-caddy-server]

**No action required.** The built-in Caddy server configuration has been automatically updated and will work without any changes on your part.

### If You're Using a Custom Reverse Proxy [#if-youre-using-a-custom-reverse-proxy]

**You need to remove any custom API path rewriting** from your reverse proxy configuration.

<Callout type="warn">
  **Important:** If you were using a custom reverse proxy (Nginx, Apache, etc.) with path rewriting rules for the `/api/` endpoint, you must remove these rules when upgrading to v1.0.
</Callout>

#### What to Remove [#what-to-remove]

Remove any configuration that strips or rewrites the `/api/` prefix when forwarding requests to the backend. Common examples include:

**Nginx - Remove these patterns:**

```nginx
# ❌ Remove this type of configuration
location /api/ {
    rewrite ^/api(/.*)$ $1 break;  # Remove this line
    proxy_pass http://localhost:3001/;  # Change trailing slash
}
```

**Update to:**

```nginx
# ✅ Correct v1.0 configuration
location /api/ {
    proxy_pass http://localhost:3001;  # No trailing slash, no rewrite
    proxy_set_header Host $host;
    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;
}
```

**Apache - Remove these patterns:**

```apache
# ❌ Remove this type of configuration
ProxyPass /api/ http://localhost:3001/
ProxyPassReverse /api/ http://localhost:3001/
```

**Update to:**

```apache
# ✅ Correct v1.0 configuration
ProxyPass /api/ http://localhost:3001/api/
ProxyPassReverse /api/ http://localhost:3001/api/
```

**Docker Compose with custom location rules:**

```yaml
# ❌ Remove rewrite rules like this
location /api/ {
    rewrite ^/api(/.*)$ $1 break;
    proxy_pass http://rybbit_backend:3001;
}
```

**Update to:**

```yaml
# ✅ Correct v1.0 configuration
location /api/ {
    proxy_pass http://rybbit_backend:3001;
}
```

#### Why This Change? [#why-this-change]

This change simplifies the reverse proxy setup and eliminates a common source of configuration errors. The backend now handles the `/api/` prefix internally, making the setup more straightforward and consistent across different proxy solutions.

## Migration Steps [#migration-steps]

1. **Backup your current configuration** before making any changes
2. **Update your reverse proxy configuration** to remove API path rewriting (if applicable)
3. **Update to v1.0** using the update script:
   ```bash
   ./update.sh
   ```
4. **Verify your setup** by checking that your Rybbit instance is accessible and functioning correctly

## Need Help? [#need-help]

If you encounter issues during migration or need assistance with your specific reverse proxy setup, feel free to join our Discord community for support.


# Compare Channel Performance (/fr/docs/api/channel-performance)





The channel that sends the most visitors is rarely the channel that sends the most *customers*. This guide ranks each acquisition channel by conversion rate so you can see which sources punch above their weight — and which ones are vanity traffic.

**Endpoints used:**

* [`GET /metric`](/docs/api/overview/metric) — sessions broken down by channel
* [`GET /goals`](/docs/api/goals/list) — conversion metrics, scoped with a channel filter

<Callout type="info">
  The key technique here is the [`filters` parameter](/docs/api/getting-started#filter-parameters). Almost every endpoint accepts it, so you can take any site-wide metric and recompute it for a single segment — here, one channel at a time.
</Callout>

## The workflow [#the-workflow]

<Steps>
  <Step>
    **List your channels** and their session counts with `metric?parameter=channel`.
  </Step>

  <Step>
    **For each channel, fetch your goal's conversion rate** by calling `/goals` with a `channel` filter applied.
  </Step>

  <Step>
    **Rank by conversion rate** to reveal which channels actually drive outcomes.
  </Step>
</Steps>

## Full script [#full-script]

This script ranks every channel by the conversion rate of a chosen goal (here, goal `1` — your signup goal). Swap in whichever goal matters to your business.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="channel-performance.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const PRIMARY_GOAL_ID = 1; // the goal you care about

    const range = { start_date: '2024-01-01', end_date: '2024-01-31', time_zone: 'America/New_York' };

    async function get(path, params) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    // 1. All channels with their session counts
    async function getChannels() {
      const { data } = await get('/metric', { parameter: 'channel', limit: 20, ...range });
      return data.data; // [{ value: 'Organic Search', count: 5400, ... }]
    }

    // 2. Conversion rate for one channel, scoped with a filter
    async function goalForChannel(channel) {
      const filters = JSON.stringify([{ parameter: 'channel', type: 'equals', value: [channel] }]);
      const { data } = await get('/goals', { filters, ...range });
      return data.find((g) => g.goalId === PRIMARY_GOAL_ID);
    }

    async function rankChannels() {
      const channels = await getChannels();

      const rows = await Promise.all(
        channels.map(async (c) => {
          const goal = await goalForChannel(c.value);
          return {
            channel: c.value || 'Direct',
            sessions: c.count,
            conversions: goal?.total_conversions ?? 0,
            // conversion_rate comes back as a 0–1 fraction
            conversionRate: (goal?.conversion_rate ?? 0) * 100,
          };
        })
      );

      return rows.sort((a, b) => b.conversionRate - a.conversionRate);
    }

    rankChannels().then((rows) => {
      console.log('Channel'.padEnd(18), 'Sessions'.padStart(10), 'Conv.'.padStart(8), 'Rate'.padStart(8));
      for (const r of rows) {
        console.log(
          r.channel.padEnd(18),
          r.sessions.toLocaleString().padStart(10),
          String(r.conversions).padStart(8),
          `${r.conversionRate.toFixed(2)}%`.padStart(8)
        );
      }
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python title="channel_performance.py"
    import os, json, requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    PRIMARY_GOAL_ID = 1  # the goal you care about

    RANGE = {"start_date": "2024-01-01", "end_date": "2024-01-31", "time_zone": "America/New_York"}

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def get(path, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def get_channels():
        # 1. All channels with their session counts
        return get("/metric", parameter="channel", limit=20, **RANGE)["data"]["data"]


    def goal_for_channel(channel):
        # 2. Conversion rate for one channel, scoped with a filter
        filters = json.dumps([{"parameter": "channel", "type": "equals", "value": [channel]}])
        goals = get("/goals", filters=filters, **RANGE)["data"]
        return next((g for g in goals if g["goalId"] == PRIMARY_GOAL_ID), None)


    def rank_channels():
        rows = []
        for c in get_channels():
            goal = goal_for_channel(c["value"])
            rows.append({
                "channel": c["value"] or "Direct",
                "sessions": c["count"],
                "conversions": goal["total_conversions"] if goal else 0,
                # conversion_rate comes back as a 0–1 fraction
                "conversion_rate": (goal["conversion_rate"] if goal else 0) * 100,
            })
        return sorted(rows, key=lambda r: r["conversion_rate"], reverse=True)


    print(f"{'Channel':<18}{'Sessions':>10}{'Conv.':>8}{'Rate':>8}")
    for r in rank_channels():
        print(f"{r['channel']:<18}{r['sessions']:>10,}{r['conversions']:>8}{r['conversion_rate']:>7.2f}%")
    ```
  </Tab>
</Tabs>

## Reading the result [#reading-the-result]

```text
Channel             Sessions   Conv.    Rate
Referral               1,820     310    17.03%
Organic Search         5,400     642    11.89%
Direct                 4,220     451    10.69%
Email                    980      88     8.98%
Paid Search            2,310     142     6.15%
Social                 6,150     119     1.93%
```

Social sends the **most** traffic (6,150 sessions) but converts the **worst** (1.93%). Referral sends a fraction of the volume but converts nine times better. The takeaway writes itself: the referral partnerships deserve more investment, and the social strategy needs a hard look before more budget goes into it.

<Callout type="warn">
  Conversion rate alone can mislead on tiny samples — Email looks healthy at 9% but it's only 88 conversions. Always show the raw `sessions` and `conversions` columns next to the rate so a channel with 12 sessions and one fluke conversion doesn't top your list.
</Callout>

## Variations [#variations]

* **By UTM campaign instead of channel:** swap `parameter: 'channel'` for `parameter: 'utm_campaign'`, and filter on `utm_campaign` in the goals call. Same code, campaign-level granularity.
* **Engagement instead of conversion:** call [`/overview`](/docs/api/overview/overview) with the channel filter to compare `bounce_rate` and `session_duration` per channel — useful when you don't have a goal defined yet.
* **Full-funnel by channel:** run [`/funnels/analyze`](/docs/api/funnels/analyze) with a channel filter to see *where* in the funnel each channel's visitors fall out, not just the final rate.

## Next steps [#next-steps]

* [Find Where Users Drop Off](/docs/api/funnel-dropoff) — once you know your best channels, fix the funnel they pour into.
* [Automated Weekly Report](/docs/api/weekly-report) — add a channel league table to a scheduled digest.


# Find Where Users Drop Off (/fr/docs/api/funnel-dropoff)





A funnel tells you *how many* people fall out at each step. The journeys endpoint tells you *where they went instead*. Putting them together turns "our signup funnel leaks at the pricing page" into "people leave the pricing page for the FAQ — they have unanswered questions."

**Endpoints used:**

* [`POST /funnels/analyze`](/docs/api/funnels/analyze) — step-by-step conversion and drop-off rates
* [`GET /journeys`](/docs/api/insights/journeys) — the most common navigation paths

## The workflow [#the-workflow]

<Steps>
  <Step>
    **Analyze the funnel** to get a drop-off rate for every step.
  </Step>

  <Step>
    **Find the worst step** — the one with the highest `dropoff_rate`.
  </Step>

  <Step>
    **Pull journeys that start at that step's page** using `stepFilters`, so you can see the most common next page for people who were there.
  </Step>
</Steps>

## Step 1 — Analyze the funnel [#step-1--analyze-the-funnel]

Define the path a converting user should take and post it to the analyze endpoint.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="Analyze the funnel"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;

    const range = { start_date: '2024-01-01', end_date: '2024-01-31', time_zone: 'America/New_York' };

    const funnelSteps = [
      { type: 'page',  value: '/',                 name: 'Homepage' },
      { type: 'page',  value: '/pricing',          name: 'Pricing' },
      { type: 'page',  value: '/signup',           name: 'Signup' },
      { type: 'event', value: 'signup_complete',   name: 'Complete' },
    ];

    async function analyzeFunnel() {
      const url = new URL(`${API}/api/sites/${SITE}/funnels/analyze`);
      Object.entries(range).forEach(([k, v]) => url.searchParams.set(k, v));

      const res = await fetch(url, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ steps: funnelSteps }),
      });
      const { data } = await res.json();
      return data; // array of { step_number, step_name, sessions, conversion_rate, dropoff_rate }
    }
    ```
  </Tab>

  <Tab value="Python">
    ```python title="Analyze the funnel"
    import os, requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]

    RANGE = {"start_date": "2024-01-01", "end_date": "2024-01-31", "time_zone": "America/New_York"}

    FUNNEL_STEPS = [
        {"type": "page",  "value": "/",               "name": "Homepage"},
        {"type": "page",  "value": "/pricing",        "name": "Pricing"},
        {"type": "page",  "value": "/signup",         "name": "Signup"},
        {"type": "event", "value": "signup_complete", "name": "Complete"},
    ]


    def analyze_funnel():
        res = requests.post(
            f"{API}/api/sites/{SITE}/funnels/analyze",
            params=RANGE,
            json={"steps": FUNNEL_STEPS},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        res.raise_for_status()
        return res.json()["data"]  # list of step results
    ```
  </Tab>
</Tabs>

A response looks like this — note that `dropoff_rate` is the percentage who left **between the previous step and this one**:

```json
{
  "data": [
    { "step_number": 1, "step_name": "Homepage", "sessions": 10000, "conversion_rate": 100,  "dropoff_rate": 0 },
    { "step_number": 2, "step_name": "Pricing",  "sessions": 4500,  "conversion_rate": 45,   "dropoff_rate": 55 },
    { "step_number": 3, "step_name": "Signup",   "sessions": 1800,  "conversion_rate": 18,   "dropoff_rate": 60 },
    { "step_number": 4, "step_name": "Complete", "sessions": 1080,  "conversion_rate": 10.8, "dropoff_rate": 40 }
  ]
}
```

## Step 2 — Find the worst step [#step-2--find-the-worst-step]

The leak isn't always the step with the fewest sessions — it's the step with the steepest **drop-off**. Pick the maximum `dropoff_rate`.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="Find the biggest leak"
    function biggestLeak(steps) {
      // Skip step 1 — it always has 0% drop-off
      return steps
        .filter((s) => s.step_number > 1)
        .reduce((worst, s) => (s.dropoff_rate > worst.dropoff_rate ? s : worst));
    }

    const steps = await analyzeFunnel();
    const leak = biggestLeak(steps);
    const enteredStep = steps[leak.step_number - 2]; // the step they were on before leaving

    console.log(
      `Worst leak: ${leak.dropoff_rate}% of users left after "${enteredStep.step_name}" ` +
      `instead of reaching "${leak.step_name}".`
    );
    ```
  </Tab>

  <Tab value="Python">
    ```python title="Find the biggest leak"
    def biggest_leak(steps):
        # Skip step 1 — it always has 0% drop-off
        return max((s for s in steps if s["step_number"] > 1), key=lambda s: s["dropoff_rate"])


    steps = analyze_funnel()
    leak = biggest_leak(steps)
    entered_step = steps[leak["step_number"] - 2]  # the step they were on before leaving

    print(
        f'Worst leak: {leak["dropoff_rate"]}% of users left after "{entered_step["step_name"]}" '
        f'instead of reaching "{leak["step_name"]}".'
    )
    ```
  </Tab>
</Tabs>

In the example above, the steepest drop-off is **60%, between Pricing and Signup** — of the 4,500 people who reached the pricing page, only 1,800 went on to signup. That makes the **pricing page** the one to investigate: it's where the audience was sitting right before the biggest leak.

## Step 3 — See where the leavers went [#step-3--see-where-the-leavers-went]

The [journeys endpoint](/docs/api/insights/journeys) ranks the most common page paths. Use `stepFilters` to anchor step `0` to the page people were dropping from — now every returned journey shows you a common *next* page for that audience.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="What did they do after the leaky page?"
    async function journeysFrom(page) {
      const stepFilters = JSON.stringify({ '0': page });
      const url = new URL(`${API}/api/sites/${SITE}/journeys`);
      url.searchParams.set('steps', '2');
      url.searchParams.set('limit', '10');
      url.searchParams.set('stepFilters', stepFilters);
      Object.entries(range).forEach(([k, v]) => url.searchParams.set(k, v));

      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      const { journeys } = await res.json();
      return journeys;
    }

    // The leaky step's page — '/pricing' in our example
    const leakyPage = funnelSteps[leak.step_number - 2].value;
    const journeys = await journeysFrom(leakyPage);

    console.log(`Where users go after ${leakyPage}:`);
    journeys
      .filter((j) => j.path[1] && j.path[1] !== '/signup') // exclude the intended next step
      .slice(0, 5)
      .forEach((j) => console.log(`  → ${j.path[1]}  (${j.count} sessions, ${j.percentage}%)`));
    ```
  </Tab>

  <Tab value="Python">
    ```python title="What did they do after the leaky page?"
    import json


    def journeys_from(page):
        res = requests.get(
            f"{API}/api/sites/{SITE}/journeys",
            params={"steps": 2, "limit": 10, "stepFilters": json.dumps({"0": page}), **RANGE},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        res.raise_for_status()
        return res.json()["journeys"]


    # The leaky step's page — '/pricing' in our example
    leaky_page = FUNNEL_STEPS[leak["step_number"] - 2]["value"]
    journeys = journeys_from(leaky_page)

    print(f"Where users go after {leaky_page}:")
    for j in [j for j in journeys if len(j["path"]) > 1 and j["path"][1] != "/signup"][:5]:
        print(f'  → {j["path"][1]}  ({j["count"]} sessions, {j["percentage"]}%)')
    ```
  </Tab>
</Tabs>

### The insight [#the-insight]

```text
Where users go after /pricing:
  → /faq          (1,240 sessions, 27.6%)
  → /             (820 sessions, 18.2%)
  → /enterprise   (610 sessions, 13.6%)
```

More than a quarter of people who hit Pricing and didn't sign up went to the FAQ — a strong signal that pricing raises questions your FAQ has to answer. That's a far more actionable finding than "the pricing page has a 60% drop-off."

<Callout type="info">
  **Quantify before you act.*&#x2A; Combine the funnel and journey numbers into a one-line business case: &#x2A;"2,700 users/month leave Pricing; 28% head to the FAQ. Surfacing the top FAQ answers on the pricing page could recover a meaningful share of them."*
</Callout>

## Next steps [#next-steps]

* [Compare Marketing Channel Performance](/docs/api/channel-performance) — find out which traffic sources fill the top of this funnel with people who actually convert.
* [Funnels API reference](/docs/api/funnels/analyze) — event steps, property matching, and per-step session lookups.


# Getting Started (/fr/docs/api/getting-started)





<Callout type="warn">
  The API is currently in beta. There may be breaking changes as we continue to improve and expand the API.
</Callout>

## API Playground [#api-playground]

The easiest way to explore and test the API is using the built-in **API Playground** in your Rybbit dashboard. Access it by navigating to any site and clicking "API Playground" in the sidebar.

The playground provides:

* **Endpoint browser** - Browse all available API endpoints
* **Parameter controls** - Configure request parameters with a visual interface
* **Exact time ranges** - Test date ranges with optional start and end times
* **Live responses** - See real API responses with your actual data
* **Code generation** - Copy ready-to-use code snippets

This is the recommended way to familiarize yourself with the API before integrating it into your applications.

## Guides [#guides]

Looking for what to *build* with the API? These end-to-end recipes chain endpoints together to solve a real problem:

* [**Automated Weekly Report**](/docs/api/weekly-report) — a scheduled digest of last week's traffic, week-over-week change, and top pages and sources.
* [**Find Where Users Drop Off**](/docs/api/funnel-dropoff) — locate the biggest leak in a funnel, then see where the people who abandon go instead.
* [**Compare Channel Performance**](/docs/api/channel-performance) — rank acquisition channels by how well they convert, not just how much traffic they send.
* [**Build a Live Visitor Feed**](/docs/api/live-feed) — poll the events endpoint for a real-time activity stream you can render or alert on.
* [**Export Events to a Warehouse**](/docs/api/export-events) — backfill your full event history and keep it in sync with an incremental job.

## Authentication [#authentication]

All API requests must include authentication using one of the following methods:

### Bearer Token (Recommended) [#bearer-token-recommended]

```bash
Authorization: Bearer your_api_key_here
```

### Query Parameter (Testing Only) [#query-parameter-testing-only]

```bash
?api_key=your_api_key_here
```

<Callout type="warn">
  Query parameters expose API keys in server logs and browser history. Use only for quick testing.
</Callout>

## Generating API Keys [#generating-api-keys]

Rybbit has two kinds of API keys:

* **Organization API keys** (recommended for integrations) — the organization's own credential. They can access every site in the organization and keep working when team members leave. Only organization admins and owners can create and manage them.
* **Personal API keys** — act as you, with exactly your access, including any site restrictions, across every organization you belong to. Best for personal scripts and for connecting MCP clients.

### Organization keys [#organization-keys]

1. Navigate to **Settings → Organization** in your Rybbit dashboard
2. Scroll to the **Organization API Keys** section (visible to admins and owners)
3. Enter a name for the key and click **Create**
4. Copy the key immediately (it won't be shown again)

### Personal keys [#personal-keys]

1. Navigate to **Settings → Account** in your Rybbit dashboard
2. Scroll to the **Personal API Keys** section
3. Enter a name for the key and click **Create**
4. Copy the key immediately (it won't be shown again)

Both kinds support restricting a key to specific permissions when you create it — leave restrictions off for a full-access key.

### Rate Limits (Cloud Only) [#rate-limits-cloud-only]

Requests are limited in two ways: a **burst** limit that is the same on every plan, and a **daily quota** that depends on your plan.

| Plan             | Burst                      | Daily quota             |
| ---------------- | -------------------------- | ----------------------- |
| **Free / Basic** | API keys not available     | —                       |
| **Standard**     | 50 requests per 10 seconds | 5,000 requests per day  |
| **Pro**          | 50 requests per 10 seconds | 25,000 requests per day |

The burst limit is a bucket of 50 requests that refills continuously at 5 requests per second. You can spend all 50 at once, then keep going at 5 per second — so short spikes are fine and there is no window boundary to line up with.

The daily quota resets at **00:00 UTC**.

Requests refused by the burst limit don't count against your daily quota.

#### Which budget a request is charged to [#which-budget-a-request-is-charged-to]

Limits apply per **credential owner**, never per key — creating more keys splits an existing budget rather than adding to it:

| Credential                       | Budget                                                                                      |
| -------------------------------- | ------------------------------------------------------------------------------------------- |
| **Organization key** (`rb_org_`) | The organization's. All of an organization's keys share it.                                 |
| **Personal key**                 | Yours. All of your personal keys share one budget, across every organization you belong to. |
| **OAuth token** (MCP)            | Yours, the same budget as your personal keys.                                               |

A personal key's quota follows the most generous plan among the organizations you belong to.

Self-hosted instances are not rate limited at all — neither tier applies, and no rate limit headers are sent.

#### Reading your remaining budget [#reading-your-remaining-budget]

Analytics and management endpoints report your current budget on every response, so you can pace a client without waiting to be rejected:

| Header                                      | Meaning                                        |
| ------------------------------------------- | ---------------------------------------------- |
| `X-RateLimit-Burst-Limit` / `-Remaining`    | Burst bucket size and tokens left              |
| `X-RateLimit-Burst-Reset`                   | Seconds until the bucket is full again         |
| `X-RateLimit-Daily-Limit` / `-Remaining`    | Daily quota and requests left today            |
| `X-RateLimit-Daily-Reset`                   | Seconds until 00:00 UTC                        |
| `RateLimit-Limit` / `-Remaining` / `-Reset` | Whichever of the two is closest to running out |

Treat these as advisory: a few endpoints resolve credentials outside the standard path and omit them. `Retry-After` on a `429` is always present.

#### When you hit a limit [#when-you-hit-a-limit]

A `429` names the limit you hit and tells you how long to wait, in seconds:

```json
{
  "error": "Rate limit exceeded",
  "scope": "daily",
  "limit": 5000,
  "retryAfter": 34200
}
```

`scope` is `burst` or `daily`, and the same value is in the `Retry-After` header. The difference matters: a `burst` rejection clears in about a second, while a `daily` one lasts until the quota resets. Back off accordingly rather than retrying straight away.

***

## Common Parameters [#common-parameters]

The following parameters are shared across all analytics endpoints.

### Time Parameters [#time-parameters]

All endpoints require date-based, exact datetime, or relative time parameters:

<TypeTable
  type="{
  start_date: {
    description: 'Start date for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD (e.g., &#x22;2024-01-15&#x22;)',
    required: false,
  },
  end_date: {
    description: 'End date for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD (e.g., &#x22;2024-01-31&#x22;)',
    required: false,
  },
  time_zone: {
    description: 'IANA timezone identifier',
    type: 'string',
    typeDescription: 'e.g., &#x22;America/New_York&#x22;, &#x22;Europe/London&#x22;, &#x22;Asia/Tokyo&#x22;. Required with date and exact datetime ranges.',
    required: false,
  },
  start_datetime: {
    description: 'Exact UTC start timestamp for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD HH:mm:ss (e.g., &#x22;2024-01-15 13:00:00&#x22;)',
    required: false,
  },
  end_datetime: {
    description: 'Exact UTC end timestamp for the query period. This boundary is exclusive.',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD HH:mm:ss (e.g., &#x22;2024-01-15 15:00:00&#x22;)',
    required: false,
  },
  past_minutes_start: {
    description: 'Start of relative time range (older boundary)',
    type: 'number',
    typeDescription: 'Minutes ago from now. Must be greater than past_minutes_end.',
    required: false,
  },
  past_minutes_end: {
    description: 'End of relative time range (newer boundary)',
    type: 'number',
    typeDescription: 'Minutes ago from now. Must be less than past_minutes_start.',
    required: false,
  },
}"
/>

**Note:** You must provide either:

* All three date parameters (`start_date`, `end_date`, `time_zone`), OR
* All three exact datetime parameters (`start_datetime`, `end_datetime`, `time_zone`), OR
* Both relative parameters (`past_minutes_start`, `past_minutes_end`)

#### Examples [#examples]

**Date-based query (last 30 days):**

```
?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York
```

**Exact datetime query (8 AM to 10 AM in New York on Jan 15, sent as UTC):**

```
?start_datetime=2024-01-15%2013:00:00&end_datetime=2024-01-15%2015:00:00&time_zone=America/New_York
```

**Relative query (last 60 minutes):**

```
?past_minutes_start=60&past_minutes_end=0
```

### Filter Parameters [#filter-parameters]

The `filters` parameter accepts a JSON-encoded array of filter objects to narrow down your data.

You can also pass `segment_id`, the ID of a [saved segment](/docs/segments), instead of or alongside `filters`. The segment's filters are expanded on the server and ANDed with any `filters` you pass. Use the [Segments endpoints](/docs/api/segments/list) to find IDs. Public and private-link callers can only use segments marked as shown on the public dashboard.

```
?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC&segment_id=12
```

#### Filter Object Structure [#filter-object-structure]

<TypeTable
  type="{
  parameter: {
    description: 'The dimension to filter on',
    type: 'FilterParameter',
    typeDescription: 'See Filter Parameters table below',
    required: true,
  },
  type: {
    description: 'The type of comparison to perform',
    type: 'FilterType',
    typeDescription: '&#x22;equals&#x22; | &#x22;not_equals&#x22; | &#x22;contains&#x22; | &#x22;not_contains&#x22; | &#x22;regex&#x22; | &#x22;not_regex&#x22; | &#x22;greater_than&#x22; | &#x22;less_than&#x22;',
    required: true,
  },
  value: {
    description: 'Array of values to match against',
    type: 'Array<string | number>',
    typeDescription: 'Multiple values are treated as OR conditions',
    required: true,
  },
}"
/>

#### Filter Types [#filter-types]

<TypeTable
  type="{
  equals: {
    description: 'Exact match',
    type: 'string',
    typeDescription: 'Value must exactly match',
  },
  not_equals: {
    description: 'Exclude exact matches',
    type: 'string',
    typeDescription: 'Value must not match',
  },
  contains: {
    description: 'Substring match',
    type: 'string',
    typeDescription: 'Value must contain the substring (uses SQL LIKE %value%)',
  },
  not_contains: {
    description: 'Exclude substring matches',
    type: 'string',
    typeDescription: 'Value must not contain the substring',
  },
  regex: {
    description: 'Regular expression match',
    type: 'string',
    typeDescription: 'Value must match the regex pattern (max 500 characters)',
  },
  not_regex: {
    description: 'Exclude regex matches',
    type: 'string',
    typeDescription: 'Value must not match the regex pattern',
  },
  greater_than: {
    description: 'Numeric greater than',
    type: 'number',
    typeDescription: 'For numeric fields like lat, lon',
  },
  less_than: {
    description: 'Numeric less than',
    type: 'number',
    typeDescription: 'For numeric fields like lat, lon',
  },
}"
/>

#### Available Filter Parameters [#available-filter-parameters]

**Browser & Device**

<TypeTable
  type="{
  browser: {
    description: 'Browser name',
    type: 'string',
    typeDescription: 'e.g., &#x22;Chrome&#x22;, &#x22;Firefox&#x22;, &#x22;Safari&#x22;',
  },
  browser_version: {
    description: 'Browser with version',
    type: 'string',
    typeDescription: 'e.g., &#x22;Chrome 120&#x22;',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
    typeDescription: 'e.g., &#x22;Windows&#x22;, &#x22;macOS&#x22;, &#x22;Linux&#x22;',
  },
  operating_system_version: {
    description: 'OS with version',
    type: 'string',
    typeDescription: 'e.g., &#x22;Windows 10/11&#x22;, &#x22;macOS 14&#x22;',
  },
  device_type: {
    description: 'Device category',
    type: 'string',
    typeDescription: '&#x22;desktop&#x22;, &#x22;mobile&#x22;, &#x22;tablet&#x22;',
  },
  dimensions: {
    description: 'Screen dimensions',
    type: 'string',
    typeDescription: 'e.g., &#x22;1920x1080&#x22;, &#x22;390x844&#x22;',
  },
  language: {
    description: 'Browser language',
    type: 'string',
    typeDescription: 'e.g., &#x22;en-US&#x22;, &#x22;es-ES&#x22;',
  },
}"
/>

**Location**

<TypeTable
  type="{
  country: {
    description: 'Country code',
    type: 'string',
    typeDescription: 'ISO 3166-1 alpha-2 code, e.g., &#x22;US&#x22;, &#x22;GB&#x22;',
  },
  region: {
    description: 'Geographic region/state',
    type: 'string',
    typeDescription: 'e.g., &#x22;California&#x22;, &#x22;England&#x22;',
  },
  city: {
    description: 'City name with region prefix',
    type: 'string',
    typeDescription: 'Format: &#x22;Region-City&#x22;, e.g., &#x22;CA-San Francisco&#x22;',
  },
  timezone: {
    description: 'User timezone',
    type: 'string',
    typeDescription: 'IANA timezone, e.g., &#x22;America/New_York&#x22;',
  },
  lat: {
    description: 'Latitude',
    type: 'number',
    typeDescription: 'Supports greater_than, less_than, equals (with 0.001 tolerance)',
  },
  lon: {
    description: 'Longitude',
    type: 'number',
    typeDescription: 'Supports greater_than, less_than, equals (with 0.001 tolerance)',
  },
}"
/>

**Page & Traffic**

<TypeTable
  type="{
  pathname: {
    description: 'URL pathname',
    type: 'string',
    typeDescription: 'e.g., &#x22;/blog/post-title&#x22;',
  },
  page_title: {
    description: 'HTML page title',
    type: 'string',
  },
  hostname: {
    description: 'Website hostname',
    type: 'string',
    typeDescription: 'e.g., &#x22;example.com&#x22;',
  },
  querystring: {
    description: 'URL query string',
    type: 'string',
    typeDescription: 'e.g., &#x22;?ref=twitter&#x22;',
  },
  referrer: {
    description: 'Referrer domain (without www)',
    type: 'string',
    typeDescription: 'e.g., &#x22;google.com&#x22;, &#x22;twitter.com&#x22;',
  },
  entry_page: {
    description: 'First page in session (landing page)',
    type: 'string',
  },
  exit_page: {
    description: 'Last page in session',
    type: 'string',
  },
  channel: {
    description: 'Marketing channel',
    type: 'string',
    typeDescription: 'e.g., &#x22;Direct&#x22;, &#x22;Organic Search&#x22;, &#x22;Social&#x22;',
  },
}"
/>

**UTM Parameters**

<TypeTable
  type="{
  utm_source: {
    description: 'UTM source parameter',
    type: 'string',
    typeDescription: 'e.g., &#x22;google&#x22;, &#x22;newsletter&#x22;',
  },
  utm_medium: {
    description: 'UTM medium parameter',
    type: 'string',
    typeDescription: 'e.g., &#x22;cpc&#x22;, &#x22;email&#x22;',
  },
  utm_campaign: {
    description: 'UTM campaign parameter',
    type: 'string',
  },
  utm_term: {
    description: 'UTM term parameter',
    type: 'string',
  },
  utm_content: {
    description: 'UTM content parameter',
    type: 'string',
  },
}"
/>

**User & Events**

<TypeTable
  type="{
  user_id: {
    description: 'User identifier',
    type: 'string',
    typeDescription: 'Matches both device fingerprint and custom identified user ID',
  },
  event_name: {
    description: 'Custom event name',
    type: 'string',
    typeDescription: 'Filters to sessions containing the event',
  },
}"
/>

#### Filter Examples [#filter-examples]

<Tabs items="['Single Filter', 'Multiple Filters', 'Contains', 'Regex', 'Numeric', 'URL-encoded']">
  <Tab value="Single Filter">
    ```json
    [
      {
        "parameter": "country",
        "type": "equals",
        "value": ["US"]
      }
    ]
    ```
  </Tab>

  <Tab value="Multiple Filters">
    Multiple filters use AND logic:

    ```json
    [
      {
        "parameter": "country",
        "type": "equals",
        "value": ["US", "CA"]
      },
      {
        "parameter": "device_type",
        "type": "equals",
        "value": ["mobile"]
      }
    ]
    ```
  </Tab>

  <Tab value="Contains">
    Substring match:

    ```json
    [
      {
        "parameter": "pathname",
        "type": "contains",
        "value": ["/blog"]
      }
    ]
    ```
  </Tab>

  <Tab value="Regex">
    Pattern match:

    ```json
    [
      {
        "parameter": "pathname",
        "type": "regex",
        "value": ["^/products/[0-9]+$"]
      }
    ]
    ```
  </Tab>

  <Tab value="Numeric">
    Geolocation comparison:

    ```json
    [
      {
        "parameter": "lat",
        "type": "greater_than",
        "value": ["37.0"]
      },
      {
        "parameter": "lat",
        "type": "less_than",
        "value": ["38.0"]
      }
    ]
    ```
  </Tab>

  <Tab value="URL-encoded">
    ```
    ?filters=%5B%7B%22parameter%22%3A%22country%22%2C%22type%22%3A%22equals%22%2C%22value%22%3A%5B%22US%22%5D%7D%5D
    ```
  </Tab>
</Tabs>

***

## Error Responses [#error-responses]

All endpoints return standard HTTP status codes:

* **200** - Success
* **400** - Bad Request (invalid parameters)
* **401** - Unauthorized (missing or invalid API key)
* **403** - Forbidden (no access to site)
* **404** - Not Found (site doesn't exist)
* **429** - Too Many Requests (rate limit exceeded)
* **500** - Internal Server Error

### Error Response Format [#error-response-format]

```json
{
  "error": "Error message describing what went wrong"
}
```


# Build a Live Visitor Feed (/fr/docs/api/live-feed)





Rybbit doesn't push a websocket stream, but the events endpoint is built for polling: pass a `since_timestamp` and you get only the events that happened after it. This guide builds a self-advancing feed loop you can wire into a dashboard, a terminal ticker, or an alerting rule.

**Endpoints used:**

* [`GET /live-user-count`](/docs/api/overview/live-visitors) — how many visitors are active right now
* [`GET /events`](/docs/api/events/list) — the event stream, polled incrementally

## How incremental polling works [#how-incremental-polling-works]

The events endpoint returns the newest events first. To stream without duplicates, remember the timestamp of the most recent event you've seen and send it as `since_timestamp` on the next request — the API returns only events newer than that, up to 500 per call.

<Steps>
  <Step>
    **Fetch the initial batch** to establish a starting watermark (the newest timestamp).
  </Step>

  <Step>
    **On an interval, request events `since_timestamp`** = your watermark.
  </Step>

  <Step>
    **Process the new events** (print, render, alert) and advance the watermark to the newest one returned.
  </Step>
</Steps>

<Callout type="info">
  `since_timestamp` returns up to **500** events per call. If you expect more than 500 events between polls (a very high-traffic site with a long interval), poll more frequently so each batch stays under the cap.
</Callout>

## Full script [#full-script]

A Node script that prints a live count plus a rolling feed of activity. The same loop drives a browser dashboard — just replace `console.log` with DOM updates.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="live-feed.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const POLL_MS = 10000; // every 10 seconds

    async function get(path, params = {}) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    async function liveCount() {
      const { count } = await get('/live-user-count', { minutes: 5 });
      return count;
    }

    function describe(e) {
      const where = e.city ? `${e.city}, ${e.country}` : e.country || 'Unknown';
      if (e.type === 'pageview')     return `👀 viewed ${e.pathname} — ${where}`;
      if (e.type === 'custom_event') return `⚡ ${e.event_name} (${e.pathname}) — ${where}`;
      if (e.type === 'outbound')     return `↗️  left via ${e.pathname} — ${where}`;
      return `• ${e.type} — ${where}`;
    }

    let watermark = null; // ISO timestamp of the newest event we've shown

    async function poll() {
      try {
        const params = watermark ? { since_timestamp: watermark } : { page_size: 20 };
        const [{ data: events }, count] = await Promise.all([get('/events', params), liveCount()]);

        // Events come back newest-first; show oldest-first so the feed reads top-to-bottom
        for (const e of [...events].reverse()) {
          console.log(`[${new Date(e.timestamp).toLocaleTimeString()}] ${describe(e)}`);
        }
        if (events.length) watermark = events[0].timestamp; // newest event becomes the new watermark

        process.stdout.write(`\n🟢 ${count} visitors online\n`);
      } catch (err) {
        console.error('poll error:', err.message);
      }
    }

    console.log('Starting live feed… (Ctrl+C to stop)');
    poll();
    setInterval(poll, POLL_MS);
    ```
  </Tab>

  <Tab value="Python">
    ```python title="live_feed.py"
    import os, time
    from datetime import datetime
    import requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    POLL_SECONDS = 10

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def get(path, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def live_count():
        return get("/live-user-count", minutes=5)["count"]


    def describe(e):
        where = f'{e["city"]}, {e["country"]}' if e.get("city") else e.get("country") or "Unknown"
        if e["type"] == "pageview":
            return f'👀 viewed {e["pathname"]} — {where}'
        if e["type"] == "custom_event":
            return f'⚡ {e["event_name"]} ({e["pathname"]}) — {where}'
        if e["type"] == "outbound":
            return f'↗️  left via {e["pathname"]} — {where}'
        return f'• {e["type"]} — {where}'


    watermark = None  # ISO timestamp of the newest event we've shown

    print("Starting live feed… (Ctrl+C to stop)")
    while True:
        try:
            params = {"since_timestamp": watermark} if watermark else {"page_size": 20}
            events = get("/events", **params)["data"]

            # Events come back newest-first; show oldest-first so the feed reads top-to-bottom
            for e in reversed(events):
                ts = datetime.fromisoformat(e["timestamp"].replace("Z", "+00:00")).strftime("%H:%M:%S")
                print(f"[{ts}] {describe(e)}")
            if events:
                watermark = events[0]["timestamp"]  # newest event becomes the new watermark

            print(f"\n🟢 {live_count()} visitors online\n")
        except Exception as err:
            print(f"poll error: {err}")
        time.sleep(POLL_SECONDS)
    ```
  </Tab>
</Tabs>

## Example output [#example-output]

```text
Starting live feed… (Ctrl+C to stop)
[14:22:01] 👀 viewed /pricing — San Francisco, US
[14:22:03] ⚡ signup (/signup) — London, GB
[14:22:05] ↗️  left via /docs — Berlin, DE

🟢 42 visitors online
```

## Turn it into an alert [#turn-it-into-an-alert]

Because each poll hands you the raw events, you can act on them instead of just printing. For example, ping a channel whenever someone hits your enterprise pricing page:

<Tabs items="['JavaScript']">
  <Tab value="JavaScript">
    ```javascript title="React to specific events"
    for (const e of events) {
      if (e.type === 'pageview' && e.pathname === '/enterprise') {
        await fetch(process.env.SLACK_WEBHOOK, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            text: `🏢 Enterprise page visit from ${e.city || e.country} (${e.referrer || 'direct'})`,
          }),
        });
      }
    }
    ```
  </Tab>
</Tabs>

<Callout type="warn">
  **Mind the daily quota.** On Rybbit Cloud, a continuous poll is measured against your plan's daily quota (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only)), not just its per-second rate. A 10-second poll running around the clock is 8,640 requests/day — over the Standard quota of 5,000, and 17,280 with the live-count call added. Poll every 20-30 seconds, or only while someone is actually watching the page, and check `X-RateLimit-Daily-Remaining` to see where you stand. Self-hosted instances are not rate limited.
</Callout>

## Next steps [#next-steps]

* [Events API reference](/docs/api/events/list) — full event object fields, plus `before_timestamp` for scrolling backwards through history.
* [Export Raw Events to Your Warehouse](/docs/api/export-events) — the same `since_timestamp` mechanism, used for durable incremental syncs instead of a live view.


# Sending Events (/fr/docs/api/sending-events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/track
    ```

    Track pageviews, custom events, performance, and errors from server-side applications, mobile apps, or any platform. An API key is optional but recommended for server-side tracking — it bypasses bot detection and domain validation. IP addresses are resolved to geolocation and user agents are parsed for browser/OS/device info.

    ### Request Body [#request-body]

    All parameters are sent in the request body as JSON.

    <TypeTable
      type="{
  site_id: {
    description: 'Your site ID',
    type: 'string',
    required: true,
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;performance&#x22; | &#x22;outbound&#x22; | &#x22;error&#x22;',
    default: 'pageview',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  hostname: {
    description: 'Domain name',
    type: 'string',
    typeDescription: 'Max 253 chars',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
    typeDescription: 'Max 512 chars',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  user_id: {
    description: 'Custom user identifier',
    type: 'string',
    typeDescription: 'Max 255 chars',
  },
  user_agent: {
    description: 'Custom user agent string - will be parsed for browser/OS/device info',
    type: 'string',
    typeDescription: 'Max 512 chars',
  },
  ip_address: {
    description: 'Custom IP for geolocation - will be resolved to location data',
    type: 'string',
    typeDescription: 'Valid IPv4 or IPv6 address',
  },
  querystring: {
    description: 'Query parameters',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  language: {
    description: 'Language code',
    type: 'string',
    typeDescription: 'e.g., &#x22;en&#x22;, &#x22;es&#x22;, &#x22;fr&#x22;',
  },
  screenWidth: {
    description: 'Screen width in logical pixels (density-independent pixels)',
    type: 'number',
  },
  screenHeight: {
    description: 'Screen height in logical pixels (density-independent pixels)',
    type: 'number',
  },
  event_name: {
    description: 'Event name (required for custom events)',
    type: 'string',
    typeDescription: 'Max 256 chars',
  },
  properties: {
    description: 'JSON string with event data (for custom events, outbound, error)',
    type: 'string',
    typeDescription: 'Max 2048 chars (4096 for error events)',
  },
  feature_flags: {
    description: 'Optional map of feature flag keys to assigned values. Useful for server-side flag evaluation and filtering analytics by flag value.',
    type: 'Record<string, string>',
    typeDescription: 'Keys max 100 chars, values max 2048 chars',
  },
}"
    />

    #### Pageview [#pageview]

    Standard page view tracking. Set `type: "pageview"` (default).

    #### Custom Event [#custom-event]

    Track custom events with optional properties. Set `type: "custom_event"`.

    <TypeTable
      type="{
  event_name: {
    description: 'Name of the custom event',
    type: 'string',
    typeDescription: 'Max 256 chars',
    required: true,
  },
  properties: {
    description: 'Event data as JSON string',
    type: 'string',
    typeDescription: 'Valid JSON, max 2048 chars',
  },
}"
    />

    #### Performance [#performance]

    Track Core Web Vitals. Set `type: "performance"`.

    <TypeTable
      type="{
  lcp: {
    description: 'Largest Contentful Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  cls: {
    description: 'Cumulative Layout Shift score',
    type: 'number',
    typeDescription: 'nullable, typically 0-1',
  },
  inp: {
    description: 'Interaction to Next Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  fcp: {
    description: 'First Contentful Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  ttfb: {
    description: 'Time to First Byte in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
}"
    />

    #### Outbound [#outbound]

    Track outbound link clicks. Set `type: "outbound"`. Pass details in the `properties` JSON string.

    <TypeTable
      type="{
  url: {
    description: 'Destination URL',
    type: 'string',
    required: true,
  },
  text: {
    description: 'Link text content',
    type: 'string',
  },
  target: {
    description: 'Link target attribute',
    type: 'string',
    typeDescription: 'e.g., &#x22;_blank&#x22;, &#x22;_self&#x22;',
  },
}"
    />

    #### Error [#error]

    Track JavaScript errors. Set `type: "error"`. `event_name` is the error type and `properties` carries the error details as a JSON string.

    <TypeTable
      type="{
  message: {
    description: 'Error message',
    type: 'string',
    typeDescription: 'Max 500 chars',
    required: true,
  },
  stack: {
    description: 'Stack trace',
    type: 'string',
    typeDescription: 'Max 2000 chars',
  },
  fileName: {
    description: 'File where error occurred',
    type: 'string',
  },
  lineNumber: {
    description: 'Line number',
    type: 'number',
  },
  columnNumber: {
    description: 'Column number',
    type: 'number',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the event was accepted',
    type: 'boolean',
  },
}"
    />

    ### Rate Limiting [#rate-limiting]

    API keys are limited to **500 requests per 10 minutes**. Exceeding the limit returns a `429` status code.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/track" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "site_id": "1",
            "type": "custom_event",
            "pathname": "/checkout",
            "event_name": "purchase",
            "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch('https://app.rybbit.io/api/track', {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer your_api_key_here',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            site_id: '1',
            type: 'custom_event',
            pathname: '/checkout',
            event_name: 'purchase',
            properties: JSON.stringify({ amount: 99.99, currency: 'USD' })
          })
        });

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests
        import json

        response = requests.post(
            'https://app.rybbit.io/api/track',
            json={
                'site_id': '1',
                'type': 'custom_event',
                'pathname': '/checkout',
                'event_name': 'purchase',
                'properties': json.dumps({'amount': 99.99, 'currency': 'USD'})
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'site_id' => '1',
            'type' => 'custom_event',
            'pathname' => '/checkout',
            'event_name' => 'purchase',
            'properties' => json_encode(['amount' => 99.99, 'currency' => 'USD'])
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/track');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/track')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          site_id: '1',
          type: 'custom_event',
          pathname: '/checkout',
          event_name: 'purchase',
          properties: { amount: 99.99, currency: 'USD' }.to_json
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "site_id":    "1",
            "type":       "custom_event",
            "pathname":   "/checkout",
            "event_name": "purchase",
            "properties": `{"amount": 99.99, "currency": "USD"}`,
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/track", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "site_id": "1",
            "type": "custom_event",
            "pathname": "/checkout",
            "event_name": "purchase",
            "properties": r#"{"amount": 99.99, "currency": "USD"}"#
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/track")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "site_id": "1",
          "type": "custom_event",
          "pathname": "/checkout",
          "event_name": "purchase",
          "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/track"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            site_id = "1",
            type = "custom_event",
            pathname = "/checkout",
            event_name = "purchase",
            properties = JsonSerializer.Serialize(new { amount = 99.99, currency = "USD" })
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/track", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Success"
    {
      "success": true
    }
    ```

    ```json title="Error"
    {
      "success": false,
      "error": "Invalid payload",
      "details": {
        "fieldErrors": {},
        "formErrors": ["Custom events require event_name"]
      }
    }
    ```
  </div>
</div>


# Automated Weekly Report (/fr/docs/api/weekly-report)





This guide builds a script you can run on a schedule (a cron job, GitHub Action, or serverless function) that pulls last week's numbers, compares them to the week before, and posts a digest to Slack, email, or anywhere else.

**Endpoints used:**

* [`GET /overview`](/docs/api/overview/overview) — headline metrics for a date range
* [`GET /metric`](/docs/api/overview/metric) — top pages and traffic sources

<Callout type="info">
  Every analytics endpoint takes the same [time parameters](/docs/api/getting-started#time-parameters). The trick behind any comparison report is simply calling the same endpoint twice with two adjacent date ranges.
</Callout>

## The workflow [#the-workflow]

<Steps>
  <Step>
    **Fetch this week's overview** for the last 7 days.
  </Step>

  <Step>
    **Fetch last week's overview** for the 7 days before that, so you can compute the change.
  </Step>

  <Step>
    **Fetch top pages and top sources** from the `metric` endpoint to add context.
  </Step>

  <Step>
    **Format and deliver** the digest.
  </Step>
</Steps>

## Full script [#full-script]

This example posts a formatted message to a Slack incoming webhook, but the `buildReport` function returns plain data you can route anywhere.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="weekly-report.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const SLACK_WEBHOOK = process.env.SLACK_WEBHOOK;
    const TZ = 'America/New_York';

    // Helper: format a Date as YYYY-MM-DD
    const ymd = (d) => d.toISOString().slice(0, 10);

    async function get(path, params) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${API_KEY}` },
      });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    async function overview(start, end) {
      const { data } = await get('/overview', {
        start_date: ymd(start),
        end_date: ymd(end),
        time_zone: TZ,
      });
      return data;
    }

    async function topMetric(parameter, start, end, limit = 5) {
      const { data } = await get('/metric', {
        parameter,
        start_date: ymd(start),
        end_date: ymd(end),
        time_zone: TZ,
        limit,
      });
      return data.data; // metric nests results under data.data
    }

    function pctChange(current, previous) {
      if (!previous) return null;
      return ((current - previous) / previous) * 100;
    }

    async function buildReport() {
      const now = new Date();
      const thisWeekStart = new Date(now); thisWeekStart.setDate(now.getDate() - 7);
      const lastWeekEnd   = new Date(now); lastWeekEnd.setDate(now.getDate() - 8);
      const lastWeekStart = new Date(now); lastWeekStart.setDate(now.getDate() - 14);

      const [thisWeek, lastWeek, topPages, topSources] = await Promise.all([
        overview(thisWeekStart, now),
        overview(lastWeekStart, lastWeekEnd),
        topMetric('pathname', thisWeekStart, now),
        topMetric('referrer', thisWeekStart, now),
      ]);

      return {
        sessions: { value: thisWeek.sessions, change: pctChange(thisWeek.sessions, lastWeek.sessions) },
        users:    { value: thisWeek.users,    change: pctChange(thisWeek.users, lastWeek.users) },
        pageviews:{ value: thisWeek.pageviews, change: pctChange(thisWeek.pageviews, lastWeek.pageviews) },
        bounceRate: thisWeek.bounce_rate,
        topPages,
        topSources,
      };
    }

    function arrow(change) {
      if (change === null) return '';
      const sign = change >= 0 ? '▲' : '▼';
      return ` ${sign} ${Math.abs(change).toFixed(1)}%`;
    }

    async function postToSlack(r) {
      const lines = [
        `*📊 Weekly Analytics Report*`,
        ``,
        `• Sessions: *${r.sessions.value.toLocaleString()}*${arrow(r.sessions.change)}`,
        `• Unique users: *${r.users.value.toLocaleString()}*${arrow(r.users.change)}`,
        `• Pageviews: *${r.pageviews.value.toLocaleString()}*${arrow(r.pageviews.change)}`,
        `• Bounce rate: *${r.bounceRate.toFixed(1)}%*`,
        ``,
        `*Top pages*`,
        ...r.topPages.map((p) => `   ${p.value} — ${p.count.toLocaleString()}`),
        ``,
        `*Top sources*`,
        ...r.topSources.map((s) => `   ${s.value || 'Direct'} — ${s.count.toLocaleString()}`),
      ];
      await fetch(SLACK_WEBHOOK, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text: lines.join('\n') }),
      });
    }

    buildReport().then(postToSlack).catch(console.error);
    ```
  </Tab>

  <Tab value="Python">
    ```python title="weekly_report.py"
    import os
    from datetime import datetime, timedelta
    import requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    SLACK_WEBHOOK = os.environ["SLACK_WEBHOOK"]
    TZ = "America/New_York"

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def ymd(d: datetime) -> str:
        return d.strftime("%Y-%m-%d")


    def get(path: str, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def overview(start, end):
        return get("/overview", start_date=ymd(start), end_date=ymd(end), time_zone=TZ)["data"]


    def top_metric(parameter, start, end, limit=5):
        # metric nests results under data.data
        return get("/metric", parameter=parameter, start_date=ymd(start),
                   end_date=ymd(end), time_zone=TZ, limit=limit)["data"]["data"]


    def pct_change(current, previous):
        return None if not previous else (current - previous) / previous * 100


    def build_report():
        now = datetime.utcnow()
        this_start = now - timedelta(days=7)
        last_end = now - timedelta(days=8)
        last_start = now - timedelta(days=14)

        this_week = overview(this_start, now)
        last_week = overview(last_start, last_end)

        return {
            "sessions": (this_week["sessions"], pct_change(this_week["sessions"], last_week["sessions"])),
            "users": (this_week["users"], pct_change(this_week["users"], last_week["users"])),
            "pageviews": (this_week["pageviews"], pct_change(this_week["pageviews"], last_week["pageviews"])),
            "bounce_rate": this_week["bounce_rate"],
            "top_pages": top_metric("pathname", this_start, now),
            "top_sources": top_metric("referrer", this_start, now),
        }


    def arrow(change):
        if change is None:
            return ""
        return f" {'▲' if change >= 0 else '▼'} {abs(change):.1f}%"


    def post_to_slack(r):
        lines = [
            "*📊 Weekly Analytics Report*", "",
            f"• Sessions: *{r['sessions'][0]:,}*{arrow(r['sessions'][1])}",
            f"• Unique users: *{r['users'][0]:,}*{arrow(r['users'][1])}",
            f"• Pageviews: *{r['pageviews'][0]:,}*{arrow(r['pageviews'][1])}",
            f"• Bounce rate: *{r['bounce_rate']:.1f}%*", "",
            "*Top pages*",
            *[f"   {p['value']} — {p['count']:,}" for p in r["top_pages"]], "",
            "*Top sources*",
            *[f"   {s['value'] or 'Direct'} — {s['count']:,}" for s in r["top_sources"]],
        ]
        requests.post(SLACK_WEBHOOK, json={"text": "\n".join(lines)})


    post_to_slack(build_report())
    ```
  </Tab>
</Tabs>

## Example output [#example-output]

```text
📊 Weekly Analytics Report

• Sessions: 15,420 ▲ 12.3%
• Unique users: 12,847 ▲ 9.8%
• Pageviews: 48,933 ▼ 2.1%
• Bounce rate: 42.8%

Top pages
   / — 8,230
   /pricing — 3,120
   /blog/getting-started — 1,940

Top sources
   google.com — 6,410
   Direct — 4,220
   twitter.com — 1,180
```

## Schedule it [#schedule-it]

Run the script every Monday morning with cron:

```bash title="crontab -e"
# Every Monday at 9:00 AM
0 9 * * 1 RYBBIT_API_KEY=xxx SLACK_WEBHOOK=https://hooks.slack.com/... node /path/to/weekly-report.js
```

<Callout type="info">
  **Want a richer report?** The same pattern extends naturally. Add `topMetric('channel', ...)` for marketing channels, `topMetric('country', ...)` for geography, or call the [`time-series` endpoint](/docs/api/overview/time-series) with `bucket=day` to attach a 7-point trend line.
</Callout>

## Next steps [#next-steps]

* [Compare Marketing Channel Performance](/docs/api/channel-performance) — go beyond traffic counts and rank sources by how well they convert.
* [Export Raw Events to Your Warehouse](/docs/api/export-events) — if you'd rather build reports in your own BI tool.


# Dashboard Embed (/fr/docs/embeds/dashboard)





The dashboard embed lets you place the main Rybbit analytics dashboard on another site with a self-contained iframe. Dashboard embeds use private-link routes with `embed=true`.

## Try It Out [#try-it-out]

Configure the private-link dashboard embed URL below. The generated snippet uses the same private-link route created in the Rybbit dashboard.

<DashboardEmbedDemo />

## Requirements [#requirements]

Dashboard embeds require a generated private link. The private link key is included in the route, for example `/{siteId}/{privateLinkKey}/main`.

Unlike [Widget Embeds](/docs/embeds/widget), dashboard embeds expose the full read-only analytics dashboard, not just the compact live visitor widget.

<Callout type="warn">
  Private links are not listed publicly, but anyone with the private link can view the dashboard. Treat the iframe URL like a shareable read-only secret.
</Callout>

## Setup [#setup]

1. Open your site in the Rybbit dashboard and click the settings icon.
2. Go to the **Dashboard Embed** tab.
3. Generate a private link if one does not already exist.
4. Choose the embed theme: light, dark, or system.
5. Choose whether to hide the dashboard sidebar.
6. Copy the generated `<iframe>` snippet and paste it anywhere on your site.

## Appearance [#appearance]

* **Theme**: `light`, `dark`, or `system`. `system` follows the viewer's operating system color-scheme preference.
* **Hide sidebar**: removes the dashboard sidebar and keeps viewers on the main dashboard page.
* **Footer**: the Rybbit footer is hidden automatically in embed mode.

## Example [#example]

```html
<iframe
  src="https://app.rybbit.io/YOUR_SITE_ID/YOUR_PRIVATE_LINK_KEY/main?embed=true&theme=system&hideSidebar=true"
  style="border: 0; width: 100%; height: 720px;"
  loading="lazy"
  title="Analytics dashboard"
></iframe>
```

If you self-host Rybbit, replace `app.rybbit.io` with your own domain.

## URL Parameters [#url-parameters]

| Parameter     | Values                    | Description                                                               |
| ------------- | ------------------------- | ------------------------------------------------------------------------- |
| `embed`       | `true`                    | Enables embed mode                                                        |
| `theme`       | `light`, `dark`, `system` | Sets the embedded dashboard color scheme. Defaults to `system`            |
| `hideSidebar` | `true`, `false`           | Hides the dashboard sidebar and keeps visitors on the main dashboard page |

When `hideSidebar=true`, only the main dashboard page is shown in the iframe. Leave it off if you want viewers to use the dashboard sidebar to navigate other analytics pages allowed by the private link.

The private key is part of the path, not a query parameter: `/{siteId}/{privateLinkKey}/main?embed=true`.


# Widget Embeds (/fr/docs/embeds/widget)





Widget Embeds let you place a compact live visitor widget on another site with a self-contained iframe. There is no script tag, no JavaScript on your site, and no dependency on the Rybbit tracking script.

## Try It [#try-it]

Configure the widget below to see how it'll look. The preview shows live data from [demo.rybbit.com](https://demo.rybbit.com).

<EmbedWidgetDemo />

## Requirements [#requirements]

The widget needs a public read-only data endpoint, so you must enable **Widget Embeds** on the site. This is separate from **Public Analytics**. Turning it on only exposes the live count, time series, and top countries to the widget endpoint, not your full dashboard.

<Callout type="info">
  Enabling Widget Embeds does **not** make your dashboard public. Only the data shown in the widget itself (visitor count, per-minute / per-hour / per-day series, top 5 countries) is accessible; no individual sessions, events, pages, or referrers are exposed.
</Callout>

## Setup [#setup]

1. Open your site in the Rybbit dashboard and click the settings icon.
2. Go to the **Widget Embeds** tab.
3. Toggle **Widget Enabled** on.
4. Pick your options: variant, time window, theme, accent color, and display settings.
5. Copy the generated `<iframe>` snippet and paste it anywhere on your site.

## Variants [#variants]

### Card [#card]

A self-contained dashboard card showing the live count, an optional bar chart of users over time, and an optional list of top countries.

| Option        | Values                         | Default | Description                                              |
| ------------- | ------------------------------ | ------- | -------------------------------------------------------- |
| Time window   | 30 minutes / 24 hours / 7 days | 30 min  | Window the count and chart cover                         |
| Bar chart     | on / off                       | on      | Show a bar chart bucketed per minute / hour / day        |
| Top countries | on / off                       | on      | List the top 5 countries in the window                   |
| Width         | 240-800 px                     | 360 px  | Iframe width; use `max-width: 100%` for responsive sites |

### Inline Pill [#inline-pill]

A compact pill that fits inline with your site's chrome, such as in a header or footer. It shows the pulsing dot, the live count over the last 30 minutes, and the Rybbit logo.

## Appearance [#appearance]

* **Theme**: `dark` or `light`. The widget background is transparent, so rounded-corner edges blend into whatever sits behind the iframe.
* **Accent color**: any hex color. Used for the pulsing live-indicator dot and the bar-chart bars. Defaults to Rybbit emerald.

## Example [#example]

```html
<iframe
  src="https://app.rybbit.io/widget/YOUR_SITE_ID?variant=card&theme=dark&minutes=30&chart=true&countries=true"
  style="border: 0; width: 360px; height: 390px; max-width: 100%;"
  loading="lazy"
  title="Live visitors"
></iframe>
```

If you self-host Rybbit, replace `app.rybbit.io` with your own domain.

## URL Parameters [#url-parameters]

You don't usually need to build the URL by hand because the dashboard generates the snippet for you, but the widget URL accepts these parameters:

| Parameter   | Values                                 | Description                               |
| ----------- | -------------------------------------- | ----------------------------------------- |
| `variant`   | `card`, `inline`                       | Layout variant                            |
| `theme`     | `dark`, `light`                        | Color scheme                              |
| `accent`    | 6-character hex, no `#`, e.g. `10b981` | Pulse / bar color                         |
| `minutes`   | `30`, `1440`, `10080`                  | Time window in minutes, card variant only |
| `chart`     | `true`, `false`                        | Show the bar chart, card variant only     |
| `countries` | `true`, `false`                        | Show top countries, card variant only     |

## Caching [#caching]

The widget HTML and the underlying stats endpoint are both cached for 60 seconds on the server, so embedding the widget on a high-traffic page won't put pressure on your Rybbit instance. The visible count refreshes once per minute.


# Errors (/fr/docs/feature-guides/errors)



The Errors tab shows JavaScript errors occurring on your website, helping you identify and fix bugs that affect user experience.

## Enabling Error Tracking [#enabling-error-tracking]

Enable error tracking in your [site settings](/docs/site-settings).

## Error Information [#error-information]

For each error, you'll see:

* **Error Type** - ReferenceError, TypeError, SyntaxError, NetworkError, etc.
* **Error Message** - The specific error message
* **Stack Trace** - The chain of function calls that led to the error
* **Affected Sessions** - Number of unique sessions in which this error occurred
* **Occurrence Count** - How many times the error was triggered
  Expanding an error shows its individual occurrences, including the timestamp and page for each event.
* **Browser & Device** - Which environments experience this error

## Using Error Data [#using-error-data]

* **Prioritize by impact** - Fix errors affecting the most users first
* **Monitor after deployments** - Watch for new errors after releasing code
* **Debug user reports** - Find the exact technical issue when users report problems
* **Track third-party issues** - Identify when external integrations are malfunctioning


# Events (/fr/docs/feature-guides/events)



The Events tab shows custom events tracked on your website.

## Setting Up Events [#setting-up-events]

See the [Track Events guide](/docs/track-events) for implementation details.

## Events Page [#events-page]

The events page includes:

* **Events Chart** - Visualize event trends over time
* **Event Log** - Recent individual event occurrences (click any row to open a details sheet)

The **Custom Events List** — all tracked events with counts — lives in the Events section of the main dashboard.

## Event Metrics [#event-metrics]

For each event in the Custom Events List:

* **Event Name** - The name you assigned to the event
* **Count** - Total times triggered in the selected period
* **Percentage** - Share of total events

## Event Properties [#event-properties]

In the Custom Events List, click the expand arrow on any event to view its properties. Properties show the key-value pairs attached to events, helping you understand event context (e.g., which product was purchased, what button was clicked).

## Filtering [#filtering]

* Click any event name to filter the dashboard to sessions containing that event
* Use the filter panel to combine event filters with other dimensions
* Filter by time range to analyze event trends


# Globe (/fr/docs/feature-guides/globe)



The Globe tab shows where your visitors connect from on an interactive map.

## View Modes [#view-modes]

### 2D Map [#2d-map]

* **Timeline** - View sessions by timeframe, click individual sessions for details
* **Coordinates** - Sessions as dots with color intensity showing traffic volume
* **Countries** - Countries highlighted by traffic volume
* **Subdivisions** - Granular view by national subdivisions

### 3D Globe [#3d-globe]

Same four views as 2D, plus:

* Rotate by dragging
* Zoom in and out
* Traffic hotspots glow

The 3D view requires a Mapbox API token. Self-hosted installations need `MAPBOX_TOKEN` in environment variables. Cloud includes this automatically.

## Time Controls [#time-controls]

Pick date ranges to see how geographic distribution changes over time.

## Filtering [#filtering]

Apply the same filters as the main dashboard to see geographic distribution for specific segments.


# User Journeys (/fr/docs/feature-guides/journeys)





<img alt="User Journeys Dashboard" src="__img0" />

User journeys show the actual paths people take as they move through your website, revealing how they flow from page to page.

## Reading the Visualization [#reading-the-visualization]

### Nodes [#nodes]

Each bar represents a page or event. Its height indicates how many users reached that point.

### Connections [#connections]

Lines between nodes show user flow. Thicker connections mean more users took that path.

### Flow Direction [#flow-direction]

The visualization flows left to right, showing progression through time.

## Key Patterns to Look For [#key-patterns-to-look-for]

* **Happy Path** - The most common route to conversion
* **Drop-off Points** - Where many users enter but few continue
* **Backtracking** - Users moving backward, often indicating confusion
* **Alternative Routes** - Unexpected paths to important pages

## Using Journey Insights [#using-journey-insights]

* **Simplify complex paths** - Create shortcuts to important pages
* **Fix drop-off points** - Investigate why users leave at certain pages
* **Amplify successful paths** - Make high-converting routes easier to follow
* **Reduce backtracking** - Improve navigation where users get lost

## Analysis Types [#analysis-types]

* **Entry point analysis** - Where do users go from a specific page?
* **Goal-based analysis** - How did converting users get there?
* **Full journey mapping** - Overall flow from entry to exit


# Main Dashboard (/fr/docs/feature-guides/main-tab)





<img alt="Main Dashboard" src="__img0" />

The main dashboard is your home base in Rybbit Analytics, showing all key metrics at a glance.

## Top Metrics [#top-metrics]

* **Unique Users** - Different people who visited your site
* **Total Sessions** - Number of visits (30-minute inactivity starts a new session)
* **Total Pageviews** - Every page load from every visitor
* **Bounce Rate** - Percentage of single-page sessions
* **Pages Per Session** - Average pages viewed per visit
* **Session Duration** - Average time spent per visit

## Time Controls [#time-controls]

Select date ranges: Today, Yesterday, Last 7/30/60 days, This Week, This Month, All Time, or a custom range.

## Filters [#filters]

Combine filters for granular analysis:

* Device type, browser, OS
* Country, city
* Referrer, UTM parameters
* Custom event properties

A set of filters you use often can be saved as a [segment](/docs/segments) from the **Segments** tab of the Filter button, then applied to any report with one click.

## Main Chart [#main-chart]

Shows your selected metric over time. Click the metric selector to switch between Users, Sessions, Pageviews, Bounce Rate, Pages Per Session, or Session Duration.

## Traffic Sources [#traffic-sources]

See where your traffic comes from:

* **Direct** - Typed URL or bookmarks
* **Search** - Google, Bing, DuckDuckGo, etc.
* **Social** - Twitter, Facebook, LinkedIn, Reddit
* **Referral** - Other websites

Click any source to filter the entire dashboard to that traffic.

## UTM Parameters [#utm-parameters]

View campaign data: utm\_campaign, utm\_source, utm\_medium, utm\_term, utm\_content.

## Additional Breakdowns [#additional-breakdowns]

* **Top Pages** - Most visited URLs with pageviews, visitors, time on page, and bounce rate
* **Entry/Exit Pages** - Where visits begin and end
* **Devices & Browsers** - Desktop/mobile/tablet split, browser and OS breakdown
* **Screen Resolutions** - What sizes your visitors use
* **Geographic Data** - Countries and regions
* **Custom Events** - Click any event to filter to sessions containing it


# Pages (/fr/docs/feature-guides/pages-tab)





<img alt="Pages Dashboard" src="__img0" />

The Pages tab shows detailed analytics for every URL on your site.

## Page Metrics [#page-metrics]

Each page displays:

* **Page URL** - The full path
* **Sessions** - Number of sessions that viewed this page
* **Average Time on Page** - How long visitors spend there

## Filtering [#filtering]

Use the same filters as the main dashboard to analyze specific segments:

* Mobile users from social media
* Desktop users who converted
* Users who triggered specific events

## Identifying Issues [#identifying-issues]

* Scan for pages with low time on page to find content that isn't engaging
* Look for pages with few sessions to find underperforming pages
* Compare entry pages to see which content attracts traffic


# Performance (/fr/docs/feature-guides/performance)





<img alt="Performance Dashboard" src="__img0" />

The Performance tab tracks Core Web Vitals from real user data.

## Enabling Performance Tracking [#enabling-performance-tracking]

Enable Web Vitals in your [site settings](/docs/site-settings).

## Web Vitals [#web-vitals]

### Largest Contentful Paint (LCP) [#largest-contentful-paint-lcp]

How long the main content takes to load.

* **Good**: Under 2.5 seconds
* **Needs Improvement**: 2.5-4 seconds
* **Poor**: Over 4 seconds

### Cumulative Layout Shift (CLS) [#cumulative-layout-shift-cls]

How much content jumps around while loading.

* **Good**: Under 0.1
* **Needs Improvement**: 0.1-0.25
* **Poor**: Over 0.25

### Interaction to Next Paint (INP) [#interaction-to-next-paint-inp]

How quickly your site responds to user interactions.

* **Good**: Under 200ms
* **Needs Improvement**: 200-500ms
* **Poor**: Over 500ms

### First Contentful Paint (FCP) [#first-contentful-paint-fcp]

How long until the first content appears.

* **Good**: Under 1.8 seconds
* **Needs Improvement**: 1.8-3 seconds
* **Poor**: Over 3 seconds

### Time to First Byte (TTFB) [#time-to-first-byte-ttfb]

How long until the server responds.

* **Good**: Under 800ms
* **Needs Improvement**: 800-1800ms
* **Poor**: Over 1800ms

## Percentile Selector [#percentile-selector]

Choose which percentile to view (p50, p75, p90, p99). The p75 is commonly used for Core Web Vitals assessment.

## Comparison [#comparison]

Each metric shows the change from the previous period, with green indicating improvement and red indicating degradation.

## Breakdowns [#breakdowns]

* **By Page** - Find your slowest pages
* **By Device** - Compare mobile vs desktop performance
* **By Browser** - Identify browser-specific issues
* **By Country** - See geographic performance differences


# Retention (/fr/docs/feature-guides/retention)





<img alt="Retention Dashboard" src="__img0" />

Retention analysis shows how many users come back to your site over time, revealing whether users find lasting value.

## Understanding Cohorts [#understanding-cohorts]

A cohort is a group of users who share a common start date. For example, all users who first visited on January 15th form one cohort.

## Reading the Retention Table [#reading-the-retention-table]

### Rows [#rows]

Each row is a different cohort, grouped by first visit date.

### Columns [#columns]

* **Day/Week 0** - Starting point (always 100%)
* **Day/Week 1, 2, 3...** - Users who returned after that period

### Numbers [#numbers]

Percentages show what portion of the original cohort returned. 40% in the "Day 7" column means 40% of users came back after a week.

### Color Coding [#color-coding]

* Lighter colors = higher retention
* Darker colors = more drop-off

## Key Insights [#key-insights]

* **Day 1 retention** - Did users find enough value to return the next day?
* **Day 7 retention** - Did users integrate your product into their routine?
* **Day 30 retention** - Have users formed a habit?

## Common Patterns [#common-patterns]

* **Cliff drop** - Sharp decline in first few days indicates onboarding issues
* **Steady decline** - Gradual drop suggests novelty wearing off
* **Plateau** - When retention levels off, you've found your core users

## Note on User ID Salting [#note-on-user-id-salting]

If [User ID Salting](/docs/site-settings) is enabled, retention beyond 24 hours becomes less accurate since user identifiers reset daily.


# Session Replay (/fr/docs/feature-guides/session-replay)





<img alt="Session Replay" src="__img0" />

Session replay lets you watch anonymized recordings of real user sessions, showing mouse movements, clicks, scrolls, and page navigation.

## Enabling Session Replay [#enabling-session-replay]

Enable session replay in your [site settings](/docs/site-settings). The tracking script picks the setting up automatically — no script tag changes are needed. (Script-tag attributes like `data-replay-batch-size` and the `data-replay-mask-*` options only tune replay behavior; the on/off switch lives in site settings.)

## What You'll See [#what-youll-see]

* Mouse movements and clicks
* Scrolling behavior
* Page navigation
* Form interactions (with PII masked)
* User details: country, device, browser

## Using Session Replay [#using-session-replay]

* **UX optimization** - Identify where users get stuck or confused
* **Debug issues** - See exactly what happened when users report problems
* **Understand behavior** - Go beyond metrics to see the full user story
* **Share with your team** - Collaborate on findings

## Privacy [#privacy]

Session replay automatically masks sensitive information. Enable PII protection in your settings for additional masking of form inputs and text content.


# Sessions (/fr/docs/feature-guides/sessions)



The Sessions tab shows individual user visits to your website, including all page views, interactions, and events during each session.

## Session Metrics [#session-metrics]

Each session displays:

* **Duration** - Time spent on site
* **Pages Visited** - Number of pages viewed
* **Events Triggered** - Custom events fired during the session
* **Device & Browser** - Technical environment
* **Location** - Geographic location based on IP
* **Entry/Exit Page** - Where the session started and ended
* **Bounce Status** - Whether the user left after one page

## Filtering Sessions [#filtering-sessions]

Filter by:

* Duration, pages visited, or events triggered
* Device type, browser, or location
* Referrer or traffic source
* Date range

## Session Replay [#session-replay]

If [session replay](/docs/product-analytics/replay-session) is enabled, you can watch a recording of any session to see exactly what the user did.


# Users (/fr/docs/feature-guides/users)



The Users tab shows unique visitors and their behavior across multiple sessions.

## User Metrics [#user-metrics]

For each user, you'll see:

* **User ID** - Anonymized identifier
* **First/Last Visit** - When they first and most recently visited
* **Total Sessions** - Number of separate visits
* **Pages Viewed** - Total pages across all sessions
* **Events Triggered** - Total custom events
* **Device Type** - Desktop, mobile, or tablet
* **Location** - Geographic location

## Filtering Users [#filtering-users]

Filter by the standard dimension filters:

* Device type, browser, or operating system
* Country, region, or city
* Referrer, channel, or UTM parameters
* Pages visited (pathname, entry, or exit page)

Session count, pageviews, events, and first/last seen aren't filters, but you can sort the user list by those columns.

## Identified Users [#identified-users]

If you use the [identify API](/docs/identify-users), you can see your own user IDs alongside the anonymous identifiers.


# Claude Code (/fr/docs/mcp/claude-code)



Connecting Claude Code to Rybbit lets it answer analytics questions mid-task — whether the error it just fixed still occurs in production, which pages get traffic before a refactor, whether a newly instrumented event is firing — and wire up goals and funnels as you ship features.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

The simplest way to connect — no API key to create or store:

```bash
claude mcp add --transport http rybbit https://app.rybbit.io/api/mcp
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Then run `/mcp` inside a Claude Code session, select **rybbit**, and choose **Authenticate**. Your browser opens to log in to Rybbit and approve access, and the connection acts with your user's role.

By default the server registers at the `local` scope — available to you in the current project only. Add `--scope user` to use it in all of your projects.

## Team setup [#team-setup]

OAuth makes the team setup trivial: commit a project-scoped `.mcp.json` at the repository root containing only the URL, and each developer authenticates once with `/mcp`. No secret ever touches the repo:

```json
{
  "mcpServers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp"
    }
  }
}
```

## Connect with an API key [#connect-with-an-api-key]

Use an [API key](/docs/mcp#1-create-an-api-key) instead when there is no browser to authenticate in (CI, headless `claude -p` runs) or when you want to hand the agent a narrower, scoped credential:

```bash
claude mcp add --transport http rybbit https://app.rybbit.io/api/mcp \
  --header "Authorization: Bearer <RYBBIT_API_KEY>"
```

In a committed `.mcp.json`, pass the key through an environment variable rather than hard-coding it — Claude Code expands `${VAR}` references from each developer's environment:

```json
{
  "mcpServers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${RYBBIT_API_KEY}"
      }
    }
  }
}
```

## Verify [#verify]

Run `claude mcp list` (or `/mcp` inside a session) to confirm the server shows as connected, then try:

> List my Rybbit sites and summarize last week's traffic for each.


# Claude Desktop (/fr/docs/mcp/claude-desktop)





Adding Rybbit as a custom connector turns Claude into a conversational analytics interface: ask how a launch went, why traffic spiked on Tuesday, or where a funnel drops off — without opening the dashboard. Connectors are shared across claude.ai, Claude Desktop, and the mobile apps.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, the full tool list, permissions, and troubleshooting.

## Add the connector [#add-the-connector]

1. Open **Settings → Connectors** (in Claude Desktop: `Cmd/Ctrl + ,`, then **Connectors**; on claude.ai: your profile menu → **Settings** → **Connectors**).

2. Click **Add custom connector**.

3. Name it **Rybbit** and paste the endpoint URL:

   ```text
   https://app.rybbit.io/api/mcp
   ```

   For a self-hosted installation, use your configured `BASE_URL` host instead.

4. Confirm, then click **Connect**. Your browser opens Rybbit's [OAuth flow](/docs/mcp#or-connect-with-oauth) — log in and approve access. The connector acts with your user's role.

There is no API key to manage: custom connectors authenticate through OAuth, and the **Advanced settings** fields (OAuth client ID and secret) can stay empty — Rybbit registers the client automatically. Custom connectors are available on all Claude plans; the Free plan is limited to one.

<Callout type="warn">
  **Self-hosted installations must be publicly reachable.** Claude connects to
  custom connectors from Anthropic's infrastructure, not from your device — a
  Rybbit instance on a private network, behind a VPN, or on `localhost` will
  not connect, even if you can reach it in your own browser.
</Callout>

## Use it [#use-it]

Once connected, Rybbit appears in the chat's tools menu — enable it there if it isn't already. Then try:

> List my Rybbit sites and summarize last month's traffic for the main one.

Claude asks for confirmation before tool calls by default; destructive tools (deleting goals, funnels, sites) are marked so it always confirms those.


# Codex (/fr/docs/mcp/codex)



Connecting Codex to Rybbit lets it check analytics as part of your development workflow — verifying that a fixed error stopped occurring, checking which routes get traffic before a refactor, or creating goals and funnels for features as you ship them.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

The simplest way to connect — add the server and log in:

```bash
codex mcp add rybbit --url https://app.rybbit.io/api/mcp
codex mcp login rybbit
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

`codex mcp login` opens your browser to log in to Rybbit and approve access; the connection acts with your user's role.

## Connect with an API key [#connect-with-an-api-key]

Use an [API key](/docs/mcp#1-create-an-api-key) instead for non-interactive runs or a narrower, scoped credential. Register the name of an environment variable holding the key:

```bash
codex mcp add rybbit --url https://app.rybbit.io/api/mcp \
  --bearer-token-env-var RYBBIT_API_KEY
```

Codex reads the key from that variable rather than storing it, so `RYBBIT_API_KEY` must be exported in the shell that launches Codex. Equivalently, configure it in `~/.codex/config.toml`:

```toml
[mcp_servers.rybbit]
url = "https://app.rybbit.io/api/mcp"
bearer_token_env_var = "RYBBIT_API_KEY"
```

## Verify [#verify]

Run `codex mcp list` (or `/mcp` inside the Codex TUI) to confirm the server is connected, then try:

> List my Rybbit sites and summarize last week's traffic for each.


# Cursor (/fr/docs/mcp/cursor)



Connecting Cursor to Rybbit lets its agent check analytics while you code — confirming an error fix landed in production, checking traffic to a route before deleting it, or setting up goals and funnels for a new feature.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Add the server [#add-the-server]

1. [Create an API key](/docs/mcp#1-create-an-api-key) in Rybbit.
2. Add the server to `~/.cursor/mcp.json` (global — available in all projects) or `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "rybbit": {
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer <RYBBIT_API_KEY>"
      }
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Prefer the global file for a personal key. If you configure the server in a project's `.cursor/mcp.json`, don't commit the key — give each developer their own, ideally [scoped](/docs/mcp#1-create-an-api-key) to what the agent needs.

## Verify [#verify]

Open **Cursor Settings → MCP**: the server should show as connected with its tool list, and can be toggled on and off there. Then ask the agent:

> List my Rybbit sites and summarize last week's traffic for each.


# MCP (/fr/docs/mcp)





Rybbit includes a hosted [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) endpoint. It gives an AI assistant read and write access to your analytics: exploring traffic and behavior data, and managing sites, goals, funnels, organization members, teams, and user profiles — through the same API the dashboard uses, with the same access checks, roles, and rate limits.

Your MCP client connects to Rybbit over HTTPS and sends your API key with each protocol request. Rybbit verifies the key before processing any message, and every tool call is authorized against the key user's role and site access.

## Connect a client [#connect-a-client]

If your client supports the MCP authorization flow — Claude Code, Codex, Claude Desktop, and opencode all do — you can [connect with OAuth](#or-connect-with-oauth) and skip API keys entirely. The steps below describe the API-key path, which works in every client and supports scoped credentials.

### 1. Create an API key [#1-create-an-api-key]

1. Open **Settings → Account** in Rybbit.
2. Create a key in the **Personal API Keys** section.
3. Copy it immediately. Rybbit only shows a new key once.

A key created without permissions can do everything its user can do. To hand an agent a narrower credential, create the key with scoped permissions (`POST /api/user/api-keys` with a `permissions` object, e.g. `{"analytics": ["read"], "goals": ["read", "write"]}`): the MCP tool list and every API call are then limited to those `resource:action` scopes. `write` implies `read` on the same resource, and scopes never elevate — org admin/owner requirements still apply. Deleting the key revokes the connection.

### 2. Add the endpoint [#2-add-the-endpoint]

Use this Streamable HTTP URL for Rybbit Cloud:

```text
https://app.rybbit.io/api/mcp
```

For a self-hosted installation, replace the host with your configured `BASE_URL`:

```text
https://analytics.example.com/api/mcp
```

Configure your client to send this header on every request:

```text
Authorization: Bearer <RYBBIT_API_KEY>
```

MCP clients use different configuration formats. A typical remote-server configuration has this shape:

```json
{
  "mcpServers": {
    "rybbit": {
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer <RYBBIT_API_KEY>"
      }
    }
  }
}
```

Use your client's secret or environment-variable support when available instead of saving the key in a file. Query-string API keys are not accepted by the MCP endpoint. Per-client walkthroughs — Claude Code, Codex, Claude Desktop, Cursor, VS Code, opencode — are in [Client guides](#client-guides) below.

### Or connect with OAuth [#or-connect-with-oauth]

Clients that support the MCP authorization flow can skip API keys entirely: add the endpoint URL with no headers, and the client discovers Rybbit's authorization server through the standard well-known metadata (`/.well-known/oauth-protected-resource`), registers itself, and opens a browser window for you to log in and approve access. The resulting access token acts with your user's role, exactly like an API key would.

OAuth grants support the same `resource:action` scopes as API keys (advertised in `scopes_supported`). A grant that requests only the standard OIDC scopes is unrestricted; a grant that requests custom scopes like `analytics:read` is limited to them. The requesting client controls which scopes it asks for — consent is currently approve-or-deny as a whole.

### 3. Start with context [#3-start-with-context]

Ask the assistant to call `list_sites`, or prompt it with something like:

> List my Rybbit sites, summarize last month's traffic for the docs site, and create a goal for signups.

`list_sites` returns the numeric `site_id` and `organization_id` required by the other tools, plus the key's role in each organization. It does not return API keys or member email addresses.

## Client guides [#client-guides]

Coding agents can use the endpoint to pull analytics into your development workflow — checking whether an error you just fixed still occurs in production, or looking up which pages matter before a refactor — and chat clients like Claude Desktop turn it into a conversational analytics interface. Follow the guide for your client:

<Cards>
  <Card icon="<SiClaude />" title="Claude Code" description="One command with OAuth or an API key, plus a no-secrets team setup" href="/docs/mcp/claude-code" />

  <Card title="Codex" description="codex mcp add, then OAuth login or a key from the environment" href="/docs/mcp/codex" />

  <Card icon="<SiClaude />" title="Claude Desktop" description="Add a custom connector on claude.ai, desktop, and mobile" href="/docs/mcp/claude-desktop" />

  <Card title="Cursor" description="mcp.json with an API key header" href="/docs/mcp/cursor" />

  <Card title="VS Code" description="Copilot agent mode, with the key kept out of the config file" href="/docs/mcp/vscode" />

  <Card title="opencode" description="Remote server config with OAuth login or env-based headers" href="/docs/mcp/opencode" />
</Cards>

Any other MCP client that supports Streamable HTTP works with the generic configuration from [step 2](#2-add-the-endpoint).

## Available tools [#available-tools]

### Analytics (read) [#analytics-read]

| Tool                      | Returns                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `get_overview`            | Sessions, pageviews, users, pages per session, bounce rate, and session duration       |
| `get_overview_timeseries` | The overview KPIs bucketed over time                                                   |
| `get_breakdown`           | Sessions broken down by one dimension (pages, referrers, countries, devices, UTM, ...) |
| `get_live_stats`          | Visitors active on the site right now                                                  |
| `get_event_names`         | Custom event names tracked on the site with counts                                     |
| `get_errors`              | JavaScript errors grouped by name/message with occurrence counts                       |
| `get_web_vitals`          | Core Web Vitals percentiles (LCP, CLS, INP, FCP, TTFB)                                 |
| `get_retention`           | User retention cohort table                                                            |
| `get_journeys`            | Most common page-to-page navigation paths                                              |
| `get_annotations`         | Notes pinned to dates on the traffic chart (launches, deploys, campaigns, outages)     |
| `list_segments`           | Saved segments: named, reusable filter sets for a site or the whole organization       |
| `apply_segment`           | Overview KPIs for visitors matching a saved segment, with its filters for reuse        |

### Sites [#sites]

| Tool                 | Does                                                                                   |
| -------------------- | -------------------------------------------------------------------------------------- |
| `list_sites`         | List organizations and sites the key can access (call this first)                      |
| `get_site`           | One site's full configuration                                                          |
| `create_site`        | Add a new site to an organization &#x2A;(admin)*                                       |
| `update_site_config` | Change site settings: name, domain, tracking features, exclusions, tags &#x2A;(admin)* |
| `delete_site`        | Permanently delete a site and its data &#x2A;(admin, destructive)*                     |

### Goals & funnels [#goals--funnels]

| Tool             | Does                                                   |
| ---------------- | ------------------------------------------------------ |
| `get_goals`      | Conversion goals with conversion stats                 |
| `create_goal`    | Create a path, event, or autocapture goal              |
| `update_goal`    | Replace a goal's definition                            |
| `delete_goal`    | Permanently delete a goal &#x2A;(destructive)*         |
| `get_funnels`    | Saved funnel definitions                               |
| `analyze_funnel` | Compute an ad-hoc funnel without saving it             |
| `save_funnel`    | Save a funnel, or update one by passing `funnel_id`    |
| `delete_funnel`  | Permanently delete a saved funnel &#x2A;(destructive)* |

### People [#people]

| Tool                 | Does                                                                        |
| -------------------- | --------------------------------------------------------------------------- |
| `get_users`          | Person inventory with per-user aggregates and traits (sortable, searchable) |
| `get_user`           | One person's profile: traits, linked devices, vitals, locations             |
| `identify_user`      | Link an anonymous device to your user ID and merge traits                   |
| `update_user_traits` | Replace a person's traits wholesale                                         |
| `delete_user`        | GDPR erasure of one person's analytics data &#x2A;(admin, destructive)*     |

### Organization & teams [#organization--teams]

| Tool                        | Does                                                           |
| --------------------------- | -------------------------------------------------------------- |
| `list_members`              | Organization members with roles, site access, and teams        |
| `add_member`                | Add an existing Rybbit user to the organization &#x2A;(admin)* |
| `update_member_site_access` | Restrict a member to specific sites &#x2A;(admin)*             |
| `list_teams`                | Teams with members and site access                             |
| `create_team`               | Create a team &#x2A;(admin)*                                   |
| `update_team`               | Rename a team or replace its members/sites &#x2A;(admin)*      |
| `delete_team`               | Permanently delete a team &#x2A;(admin, destructive)*          |

### Raw data & SQL [#raw-data--sql]

| Tool               | Does                                                                   |
| ------------------ | ---------------------------------------------------------------------- |
| `get_sessions`     | Recent visitor sessions with full attribution                          |
| `get_session`      | One session's detail plus its event timeline                           |
| `get_events`       | Raw recent events, newest first                                        |
| `get_query_schema` | The ClickHouse schema and rules for `run_query`                        |
| `run_query`        | Read-only ClickHouse SQL against the site-scoped `scoped_events` table |

Analytics tools accept optional time inputs (`start_date`/`end_date` with an IANA `time_zone`, or `past_minutes`) and the same filters as the dashboard. Omitting time inputs queries all time; an unrecognized `time_zone` is rejected before the call is made. `get_sessions`, `get_events`, and `get_users` accept an optional `fields` list to return only the named row columns, which keeps large result sets small.

## Permissions and roles [#permissions-and-roles]

The MCP surface mirrors the REST API's permission model:

* **Read tools** work for any member with access to the site.
* **Write tools** need at least member-level site access (goals, funnels, `identify_user`, `update_user_traits`, `save_funnel`).
* **Tools marked &#x2A;(admin)*** require the API key's user to hold the **admin or owner** role in the organization; `add_member` can grant the `owner` role only from an owner's key. The REST layer enforces all of this — an underprivileged key gets a 403 with an explanatory message.

To give an assistant a read-only or read-mostly view, create a **scoped** API key (see step 1): grant only the `resource:action` scopes it needs — e.g. `{"analytics": ["read"], "sessions": ["read"]}` for a reporting agent. The MCP tool list is filtered to those scopes, and any out-of-scope call returns `403 { "error": "Insufficient scope", "required": "goals:write" }`. Alternatively, connecting with a member-role user's key hides nothing but refuses every call requiring the admin/owner role.

OAuth clients request scopes through the standard grant. Rybbit advertises the same `resource:action` scopes in its discovery metadata; a grant carrying no custom scopes (or only the standard OIDC scopes) is treated as full access, for backward compatibility.

## Destructive tools [#destructive-tools]

`delete_goal`, `delete_funnel`, `delete_site`, `delete_team`, and `delete_user` permanently destroy data and are marked with the MCP `destructiveHint` annotation, so well-behaved clients ask for confirmation before invoking them. `delete_site` and `delete_user` (the GDPR-erasure path) also remove recorded events and replays, with erasure completing asynchronously.

## Data and security boundary [#data-and-security-boundary]

* The API key is verified before any MCP message is processed, and each tool call re-runs the corresponding REST route's own access checks, role requirements, and rate limits.
* The surface returns whatever the REST API returns for your role — including session-level records and, where a site has IP tracking enabled, visitor IP addresses. Connect only AI clients you trust with that data, and use a separate, revocable API key per integration.
* Text originating in tracked traffic (page titles, paths, referrers, event names, traits) is stripped of control and bidi-override characters. AI clients should still treat these values as untrusted data, never as instructions.
* `run_query` is restricted to a read-only, site-scoped table with row and execution-time caps.
* The server does not contain an AI model or send analytics to an AI provider. Data only leaves Rybbit in response to the MCP client you configure.
* The endpoint is stateless. Each HTTP request is independently authenticated.

## Troubleshooting [#troubleshooting]

* **401 Unauthorized:** The client did not send a Bearer credential, or the key/token is invalid, expired, or revoked. OAuth-capable clients re-authenticate automatically via the `WWW-Authenticate` challenge.
* **OAuth login loop or "table does not exist" (self-hosted):** Run `npm run db:push` in `server/` to create the OAuth tables, then retry.
* **403 in tool results:** The key's user lacks access to that site or organization — or the tool requires an org admin/owner role. Check the `role` field in `list_sites`.
* **403 "Insufficient scope":** The credential was created without the `resource:action` scope this tool needs (the `required` field names it). Use a key or OAuth grant that includes it.
* **429 Too Many Requests:** The API key exceeded its plan's rate limit.
* **503 Service Unavailable:** Rybbit could not verify the key. Retry the request; do not replace a known-valid key based on this response.
* **405 Method Not Allowed on GET:** This is expected. The stateless endpoint accepts MCP messages over `POST`.
* **Site access error:** Call `list_sites` again. Membership or site permissions may have changed.


# opencode (/fr/docs/mcp/opencode)



Connecting opencode to Rybbit lets it pull analytics into your terminal workflow — verifying an error fix in production, checking a route's traffic before removing it, or wiring up goals and funnels as you ship.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

Add the server to `opencode.json` at your project root (or your global opencode config):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rybbit": {
      "type": "remote",
      "url": "https://app.rybbit.io/api/mcp",
      "enabled": true
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Then authenticate:

```bash
opencode mcp auth rybbit
```

Your browser opens Rybbit's [OAuth flow](/docs/mcp#or-connect-with-oauth) — log in and approve access. The connection acts with your user's role, and the committed config carries no secret. `opencode mcp logout rybbit` removes the stored credential.

## Connect with an API key [#connect-with-an-api-key]

To use an [API key](/docs/mcp#1-create-an-api-key) instead — for non-interactive runs or a narrower, scoped credential — add a headers block that reads the key from the environment, so the config stays committable:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rybbit": {
      "type": "remote",
      "url": "https://app.rybbit.io/api/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:RYBBIT_API_KEY}"
      }
    }
  }
}
```

## Verify [#verify]

Run `opencode mcp list` to see the server and its authentication status (`opencode mcp debug rybbit` gives detailed diagnostics), then try:

> List my Rybbit sites and summarize last week's traffic for each.


# VS Code (/fr/docs/mcp/vscode)



Connecting VS Code to Rybbit gives Copilot's agent mode access to your analytics — checking whether a fixed error still occurs, looking up which pages matter before a refactor, or creating goals for a feature as you build it.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Add the server [#add-the-server]

1. [Create an API key](/docs/mcp#1-create-an-api-key) in Rybbit.
2. Create `.vscode/mcp.json` in your workspace. The `inputs` block keeps the key out of the file — VS Code prompts for it once when the server first starts and stores it securely, so this file is safe to commit:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "rybbit-api-key",
      "description": "Rybbit API key",
      "password": true
    }
  ],
  "servers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:rybbit-api-key}"
      }
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

To make the server available in every workspace instead, run **MCP: Open User Configuration** from the Command Palette and add the same JSON there. **MCP: Add Server** offers a guided setup as an alternative to editing the file.

## Verify [#verify]

Run **MCP: List Servers** from the Command Palette — Rybbit should be listed with its tools, which also appear in the tools picker in Copilot's agent mode. Then ask the agent:

> List my Rybbit sites and summarize last week's traffic for each.


# Angular (/fr/docs/guides/angular)





An Angular CLI project serves one HTML shell, `src/index.html`, for every route. Paste the snippet into its `<head>` and the script loads once for the whole app.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Angular [#add-the-snippet-to-angular]

    Open `src/index.html` and paste the snippet just before `</head>`:

    ```html title="src/index.html"
    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>MyAngularApp</title>
      <base href="/">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
      <app-root></app-root>
    </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Navigation through the Angular Router is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Declare `rybbit` on `window` once so TypeScript accepts the call, then call `window.rybbit.event()` from any component or service. Guard the call so a blocked script does not throw.

```typescript title="src/app/feature/feature.component.ts"
import { Component } from "@angular/core";

declare global {
  interface Window {
    rybbit?: {
      event: (eventName: string, eventData?: Record<string, any>) => void;
      pageview: () => void;
    };
  }
}

@Component({
  selector: "app-feature",
  template: `<button (click)="onFeatureClick()">Use Feature</button>`,
})
export class FeatureComponent {
  onFeatureClick(): void {
    if (window.rybbit) {
      window.rybbit.event("feature_used", { featureName: "Amazing Feature" });
    }
  }
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: this is rare. If it happens, subscribe to `Router.events`, filter for `NavigationEnd` and call `window.rybbit.pageview()`; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ASP.NET Core (/fr/docs/guides/aspnet)





ASP.NET Core MVC and Razor Pages apps share one layout file, `_Layout.cshtml`, that wraps every view, so the snippet goes into its `<head>`. Keep the site ID in `appsettings.json` and inject `IConfiguration` into the layout so nothing is hard-coded.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ASP.NET Core [#add-the-snippet-to-aspnet-core]

    #### Configure the site ID [#configure-the-site-id]

    Add a `Rybbit` section to `appsettings.json`:

    ```json filename="appsettings.json"
    {
      "Rybbit": {
        "InstanceUrl": "https://app.rybbit.io",
        "SiteId": "YOUR_SITE_ID"
      }
    }
    ```

    To keep the ID out of source control or vary it per environment, leave `SiteId` empty in `appsettings.json` and set it in `appsettings.Production.json`, or as the environment variable `Rybbit__SiteId` (double underscore separates configuration sections).

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open the layout file:

    * Controllers with views: `Views/Shared/_Layout.cshtml`
    * Razor Pages: `Pages/Shared/_Layout.cshtml`

    Inject `IConfiguration` at the top and add the tag inside `<head>`:

    ```razor filename="Views/Shared/_Layout.cshtml"
    @inject IConfiguration Configuration
    @{
        var rybbitSiteId = Configuration["Rybbit:SiteId"];
        var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
    }
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>@ViewData["Title"] - MyApp</title>
        <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />

        @if (!string.IsNullOrEmpty(rybbitSiteId))
        {
            <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
        }
    </head>
    ```

    If `Microsoft.Extensions.Configuration` is not already imported in `_ViewImports.cshtml`, add `@using Microsoft.Extensions.Configuration` above the `@inject` line.

    The `@if` guard skips the tag when `SiteId` is empty, so development is not tracked unless you set the value there. If your app has more than one layout, add the tag to each, or move it into a partial view and render it with `<partial name="_Rybbit" />` from every layout.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: environment-specific files such as `appsettings.Development.json` override `appsettings.json`, so check which environment you are running (`ASPNETCORE_ENVIRONMENT`) and that the `Rybbit` section exists there or in the base file. Environment variables override both.
* **Content Security Policy**: if middleware adds a `Content-Security-Policy` header, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Response caching or output caching**: the tag is rendered server-side, so a cached response keeps whatever configuration was active when it was cached. Clear the cache after changing the site ID.
* **Self-hosted instance**: set `Rybbit:InstanceUrl` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Astro (/fr/docs/guides/astro)





Astro pages share a layout component that renders the `<html>` document. Add the snippet to the `<head>` of that layout and every page that uses it is tracked.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Astro [#add-the-snippet-to-astro]

    Open your shared layout, usually `src/layouts/Layout.astro`, and paste the snippet inside `<head>`. Add `is:inline` so Astro leaves the tag as-is instead of bundling it:

    ```astro title="src/layouts/Layout.astro"
    ---
    const { title } = Astro.props;
    ---
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title>{title}</title>
        <script is:inline src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <slot />
      </body>
    </html>
    ```

    If you do not use a shared layout, add the same tag to the `<head>` of each page in `src/pages/`. A layout is easier to maintain.

    Astro builds a multi-page site by default, so each navigation is a full page load and a new pageview. With [view transitions](https://docs.astro.build/en/guides/view-transitions/) enabled, client-side navigation is tracked automatically when the URL changes.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a client-side `<script>` in any `.astro` component, or from inside a framework island the same way you would in that framework.

```astro title="src/components/TrackedButton.astro"
<button id="tracked-button">Click me</button>

<script>
  document.getElementById("tracked-button")?.addEventListener("click", () => {
    if (window.rybbit) {
      window.rybbit.event("astro_button_click", { source: "TrackedButton.astro" });
    }
  });
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing with view transitions**: this is rare. If it happens, listen for Astro's `astro:after-swap` event in a client-side script and call `window.rybbit.pageview()`; test the default behaviour first.
* **Proxying through your own domain**: Astro can serve the script from your domain with SSR middleware. See the [Astro proxy guide](/docs/proxy-guide/astro).

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# BigCommerce (/fr/docs/guides/bigcommerce)





BigCommerce's **Script Manager** adds scripts to every storefront page without theme edits, and it is also where the order-confirmation purchase event goes. Editing the theme's `head.html` works too.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to BigCommerce [#add-the-snippet-to-bigcommerce]

    <Tabs items="[&#x22;Script Manager&#x22;, &#x22;Theme files&#x22;]">
      <Tab>
        1. In the control panel, go to **Storefront > Script Manager** and click **Create a Script**.
        2. Fill in the settings:
           * **Name**: Rybbit Analytics
           * **Placement**: Head
           * **Location**: All pages
           * **Script category**: Analytics
           * **Script type**: Script
        3. Paste the snippet into **Script contents** and click **Save**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Back up your theme before editing files.
        </Callout>

        1. Go to **Storefront > Themes**, click **Advanced** on your current theme, then **Edit Theme Files**.
        2. Open **templates > components > common** and then `head.html`.
        3. Paste the snippet at the end of the file, before the closing `</head>` tag, and click **Save**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Create a second script in Script Manager with **Placement: Footer**, **Location: Order Confirmation** and **Script type: Script**. BigCommerce runs Script Manager contents through Handlebars, so expressions such as `checkout.order.id` are filled in with the order data before the page is served:

```html
<script>
(function () {
  function waitForRybbit(callback, timeout) {
    var start = Date.now();
    (function check() {
      if (window.rybbit && typeof window.rybbit.event === 'function') {
        callback();
      } else if (Date.now() - start < timeout) {
        setTimeout(check, 100);
      }
    })();
  }

  waitForRybbit(function () {
    {{#if checkout.order}}
    window.rybbit.event('purchase', {
      transaction_id: '{{checkout.order.id}}',
      value: {{checkout.subtotal.value}},
      currency: '{{checkout.currency.code}}'
    });
    {{/if}}
  }, 5000);
})();
</script>
```

`waitForRybbit` polls until the tracking script from the head has defined `window.rybbit`, so the event is not lost if the confirmation page runs the footer script first.

## Troubleshooting [#troubleshooting]

* **Script not on the page**: confirm the script is enabled in Script Manager, then purge the store cache under **Server Settings > Store-level caching > Purge cache**.
* **Purchase event missing**: the purchase script must use the **Order Confirmation** location, and the `checkout.order`, `checkout.subtotal` and `checkout.currency` Handlebars objects depend on your BigCommerce checkout version. Place a test order to confirm the event arrives.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Blazor (/fr/docs/guides/blazor)





Where the snippet goes depends on the Blazor hosting model: a Blazor Web App keeps its `<head>` in `Components/App.razor`, a standalone Blazor WebAssembly app in `wwwroot/index.html`, and a Blazor Server app (.NET 7 and earlier) in `Pages/_Host.cshtml`. In each case the tag is added once and stays on the page while Blazor handles navigation client-side.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Blazor [#add-the-snippet-to-blazor]

    <Tabs items="[&#x22;Blazor Web App&#x22;, &#x22;Blazor WebAssembly (standalone)&#x22;, &#x22;Blazor Server (.NET 7 and earlier)&#x22;]">
      <Tab>
        `App.razor` is rendered on the server, so it can read the site ID from `appsettings.json`. Add a `Rybbit` section:

        ```json filename="appsettings.json"
        {
          "Rybbit": {
            "InstanceUrl": "https://app.rybbit.io",
            "SiteId": "YOUR_SITE_ID"
          }
        }
        ```

        Then inject `IConfiguration` in `Components/App.razor` and add the tag inside `<head>`:

        ```razor filename="Components/App.razor"
        @inject IConfiguration Configuration
        @{
            var rybbitSiteId = Configuration["Rybbit:SiteId"];
            var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
        }
        <!DOCTYPE html>
        <html lang="en">

        <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <base href="/" />
            <link rel="stylesheet" href="@Assets["app.css"]" />
            <HeadOutlet />

            @if (!string.IsNullOrEmpty(rybbitSiteId))
            {
                <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
            }
        </head>
        ```

        Override the value per environment with `appsettings.Production.json` or the environment variable `Rybbit__SiteId`.
      </Tab>

      <Tab>
        A standalone WebAssembly app ships `wwwroot/index.html` as a static file, so add the tag directly inside `<head>`:

        ```html filename="wwwroot/index.html"
        <head>
            <base href="/" />
            <link rel="stylesheet" href="css/app.css" />

            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        The site ID is public on every platform (it is in the page source), so a static value here is fine; `wwwroot/appsettings.json` is equally visible to the browser and offers no advantage for this value.
      </Tab>

      <Tab>
        Add the `Rybbit` section to `appsettings.json` as in the Blazor Web App tab, then open `Pages/_Host.cshtml` (or `Pages/_Layout.cshtml` in .NET 6 projects, where the `<head>` lives) and add the tag:

        ```razor filename="Pages/_Host.cshtml"
        @page "/"
        @using Microsoft.Extensions.Configuration
        @inject IConfiguration Configuration
        @{
            var rybbitSiteId = Configuration["Rybbit:SiteId"];
            var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
        }
        <!DOCTYPE html>
        <html lang="en">
        <head>
            <base href="~/" />
            <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

            @if (!string.IsNullOrEmpty(rybbitSiteId))
            {
                <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
            }
        </head>
        ```
      </Tab>
    </Tabs>

    #### Navigation [#navigation]

    Blazor's router, `NavigationManager.NavigateTo` and enhanced navigation in Blazor Web Apps all update the URL through `history.pushState` (or `replaceState` when `replace: true`) rather than reloading the page. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). Enhanced navigation patches the DOM without re-running scripts already in `<head>`, which is what you want: the tracker loads once and keeps running. `NavigateTo(url, forceLoad: true)` and links with `data-enhance-nav="false"` do a full page load, which the script tracks as a new pageview.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in a Blazor Web App**: `App.razor` reads server-side configuration, so check the `appsettings` file for the active `ASPNETCORE_ENVIRONMENT`; environment variables override the files.
* **Blazor WebAssembly PWA**: `index.html` is cached by the service worker. Users receive the new tag only after the app is republished and the service worker updates.
* **Content Security Policy**: if you set one, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `Rybbit:InstanceUrl` (or the static URL in `index.html`) to your own domain without a trailing slash.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Bolt (/fr/docs/guides/bolt)





Bolt has no settings field for custom head code (its **Analytics** project setting only shows traffic for published sites), so the snippet goes into the app's HTML head as a code change: prompt Bolt to add it, or switch to Code view and paste it into the root HTML or layout file. Publish the project again afterwards.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Bolt [#add-the-snippet-to-bolt]

    <Tabs items="[&#x22;Ask Bolt&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of every page and keep all existing head tags:
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Review the change Bolt makes before you move on: the tag should be in the document head, not inside a component.
      </Tab>

      <Tab>
        Click the **Code Preview** icon (`<>`) at the top center to switch to Code view, then open the file that owns the `<head>` for the framework Bolt chose:

        * **Vite** projects (React, Vue, Svelte): `index.html` at the project root.
        * **Next.js** projects: `app/layout.tsx`, using the `next/script` component as in the [Next.js guide](/docs/guides/react/next-js).
        * Any other framework: ask Bolt "which file renders the HTML head?" and edit that one.

        For a Vite project, paste the snippet before `</head>`:

        ```html title="index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Click **Save** or press **Ctrl+S**.
      </Tab>
    </Tabs>

    Publish the change: open the **Publish** menu and click **Publish** the first time, or **Update** for a site that is already live. In-app navigation is tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Published site unchanged**: edits are not applied to the live site until you click **Update** in the **Publish** menu.
* **Bolt removed the tag**: later prompts can regenerate `index.html` or the layout. Right-click the file in the **Files** list and choose **Lock file** so Bolt leaves it alone, or add a line to the project's **Knowledge** telling it to keep the Rybbit script.
* **Expo (mobile) projects**: a script tag only runs in the web build. For the native app, use the [JavaScript SDK](/docs/sdks/web) instead.
* **Numbers differ from Bolt's Analytics**: Bolt's built-in counts include crawlers and bots; Rybbit filters them.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Bubble.io (/fr/docs/guides/bubble)





Bubble adds custom header code to every page of your app through the **SEO / metatags** settings tab, so the snippet goes there once and ships with your next deploy.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Bubble.io [#add-the-snippet-to-bubbleio]

    1. Open your app in the Bubble editor and click the **Settings** tab in the left sidebar.
    2. Open the **SEO / metatags** sub-tab.
    3. Scroll to **Script/meta tags in header** and paste the snippet. It is added to the `<head>` of every page in the app.
    4. Deploy the app to **Live**. The development version does not pick up the change until you deploy.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Bubble workflows can run arbitrary JavaScript through a **Run JavaScript** action (provided by the free Toolbox plugin). Use it to send events from any workflow trigger.

1. Open the **Workflow** tab and pick the trigger, for example *When Button Signup is clicked*.
2. Add a **Run JavaScript** action.
3. Paste the call, using Bubble's dynamic expressions for the values:

```javascript
if (window.rybbit) {
  window.rybbit.event("signup_clicked", {
    plan: "Current User's Plan",
  });
}
```

## Troubleshooting [#troubleshooting]

* **Only the first pageview is tracked**: Bubble apps that switch between groups on a single page do not change the URL, so there is nothing for the script to detect. Add a **Run JavaScript** action that calls `window.rybbit.pageview()` when the group becomes visible, or track those views as custom events. Apps that navigate between real Bubble pages are tracked automatically.
* **Snippet missing on the live site**: the header script is versioned with your app, so check that you deployed to Live after saving the setting.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Capacitor (/fr/docs/guides/capacitor)





Capacitor wraps a normal web app in a native WebView, so the snippet goes in the `<head>` of that web app's `index.html` and ships to iOS and Android with `npx cap sync`. If the app is built with Ionic Angular, React or Vue, follow the [Angular](/docs/guides/angular), [React](/docs/guides/react/vite-cra) or [Vue](/docs/guides/vue/vite) guide for where the tag lives, then come back here for the WebView origin settings.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Capacitor [#add-the-snippet-to-capacitor]

    1. Paste the snippet into the `<head>` of your web app's `index.html` (the file in the `webDir` folder from `capacitor.config`, after your framework's build):

    ```html title="index.html"
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    2. Enable `CapacitorHttp`, which routes `window.fetch` through native HTTP. The iOS WebView runs on `capacitor://localhost`, and Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so without this the browser blocks the requests on iOS:

    ```ts title="capacitor.config.ts"
    import type { CapacitorConfig } from "@capacitor/cli";

    const config: CapacitorConfig = {
      appId: "com.example.app",
      appName: "My App",
      webDir: "dist",
      plugins: {
        CapacitorHttp: {
          enabled: true,
        },
      },
    };

    export default config;
    ```

    3. Build the web app, then copy it into the native projects:

    ```bash
    npm run build
    npx cap sync
    ```

    Android serves the app from `https://localhost` (`server.androidScheme` defaults to `https`), which is a regular origin, so tracking works there with or without `CapacitorHttp`. In-app route changes are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.

    <Callout type="info">
      Use the script tag rather than the `@rybbit/js` npm package on Capacitor. The package sends events with `navigator.sendBeacon`, which `CapacitorHttp` does not patch, so its requests from `capacitor://localhost` are still blocked on iOS.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Works on Android and in the browser, silent on iOS**: `CapacitorHttp` is not enabled, or the native projects were not re-synced after changing the config. Run `npx cap sync` and rebuild in Xcode.
* **Changes do not appear on device**: `npx cap sync` copies the built web bundle; edit the source, rebuild the web app, then sync again.
* **Live reload during development**: with `server.url` pointing at your dev server the WebView loads an `http://` origin, so requests succeed even without `CapacitorHttp`. Do not read a working dev build as proof that the production build is configured.
* **Every pageview shows `localhost` as hostname**: expected. `server.hostname` defaults to `localhost` on both platforms; filter by site, not hostname.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Carrd (/fr/docs/guides/carrd)





Carrd builds one-page sites, and the snippet goes into the **Head** embed code field in the site settings.

<Callout type="warn">
  Custom head code requires a **Carrd Pro** subscription (Pro Standard or Pro Plus). The Embed Code feature is not included on Pro Lite.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Carrd [#add-the-snippet-to-carrd]

    1. Open your site in the Carrd editor and click the **Settings** gear in the top right.
    2. Open the **Settings** tab and scroll to **Embed Code**.
    3. Paste the following into the **Head** field:

    ```html
    <script>
      (function () {
        var s = document.createElement("script");
        s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
        s.defer = true;
        document.head.appendChild(s);
      })();
    </script>
    ```

    This wraps the snippet in a small loader so Carrd's embed processing cannot rewrite the tag.

    4. Click **Save**, then **Publish**. Changes are not live until you publish.

    If your site has multiple pages (a Pro Plus feature), the head code loads on all of them.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **The Head field is missing**: the site is on Pro Lite or the free plan. Upgrade to Pro Standard or Pro Plus.
* **Snippet not in the page source**: the site was saved but not published. Publish again from the editor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Chrome extension (/fr/docs/guides/chrome-extension)





Manifest V3 requires every piece of executable code to ship inside the extension package, and the `extension_pages` Content Security Policy is fixed at `script-src 'self' 'wasm-unsafe-eval'; object-src 'self'` with no way to relax it. A remote `<script>` tag can therefore never load in an extension page. Bundle the `@rybbit/js` SDK into your popup, options or side panel page instead, and grant `host_permissions` for the analytics host.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.

    You only need the site ID from the snippet; the script tag itself is not used in an extension.
  </Step>

  <Step>
    ### Add the snippet to Chrome extension [#add-the-snippet-to-chrome-extension]

    1. Install the SDK in the extension project:

    ```bash
    npm install @rybbit/js
    ```

    2. Initialise it in the entry script of each extension page you want to track (the popup from `action.default_popup`, the options page from `options_ui.page`, the side panel from `side_panel.default_path`). The SDK needs `window` and `document`, so do not import it in the service worker.

    ```js title="src/popup.js"
    import rybbit from "@rybbit/js";

    await rybbit.init({
      analyticsHost: "https://app.rybbit.io/api",
      siteId: "YOUR_SITE_ID",
    });

    // Extension pages have URLs like chrome-extension://<id>/popup.html.
    // Report a readable path instead:
    rybbit.pageview("/popup");
    ```

    3. Grant the extension permission to call the analytics host. Requests from extension pages to origins listed in `host_permissions` are not subject to CORS:

    ```json title="manifest.json"
    {
      "manifest_version": 3,
      "host_permissions": ["https://app.rybbit.io/*"]
    }
    ```

    4. Build the extension with your bundler (Vite, webpack, Rollup) so `@rybbit/js` ends up inside the package, then reload the unpacked extension at `chrome://extensions`.

    The default extension CSP does not restrict `connect-src`, so no `content_security_policy` entry is required. If you define your own policy, add `https://app.rybbit.io` to its `connect-src`.

    <Callout type="warn">
      Do not initialise the SDK in a content script. Content scripts run inside third-party websites; tracking there records other people's pages under your site ID, and content scripts are subject to the host page's same-origin policy in any case.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `rybbit.event()` from the page script, or use data attributes on buttons in your popup HTML:

```js title="src/popup.js"
document.getElementById("save")?.addEventListener("click", () => {
  rybbit.event("settings_saved", { theme: "dark" });
});
```

```html title="popup.html"
<button data-rybbit-event="upgrade_click" data-rybbit-prop-plan="pro">Upgrade</button>
```

## Troubleshooting [#troubleshooting]

* **`Refused to load the script` in the popup console**: the fixed `extension_pages` CSP blocked a remote tag. Remove it and use the SDK.
* **`POST /api/track` blocked by CORS**: `host_permissions` is missing or does not match. The pattern must include the path wildcard: `https://app.rybbit.io/*`.
* **Self-hosted Rybbit**: replace `https://app.rybbit.io` in both `analyticsHost` and `host_permissions` with your own instance URL.
* **Every pageview shows the extension ID as hostname**: expected. Extension pages live on `chrome-extension://<id>`; use `rybbit.pageview("/name")` for readable paths.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Circle (/fr/docs/guides/circle)





Circle has a **Code snippets** setting that injects custom code into the `<head>` of every page in your community, so the snippet goes there once and covers public pages and logged-in member pages alike.

<Callout type="info">
  Custom CSS/JavaScript snippets are included on all current Circle plans (Professional, Business and Circle Plus).
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Circle [#add-the-snippet-to-circle]

    1. Open your community as an admin and go to **Settings**.
    2. Open **Code snippets**.
    3. Paste the snippet into the **Head code snippets** field.
    4. Click **Save**. Changes apply to the whole community immediately; there is no publish step.

    Circle's own help article for this setting is [Custom code snippets](https://help.circle.so/p/administration/site-management/custom-code-snippets).

    Circle is a single-page app: after the first load, navigating between spaces, posts and courses changes the URL without a full reload. The script tracks these client-side route changes automatically, so each space and post shows up as its own pageview.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Custom domain**: the same head code is served on `yourcommunity.circle.so` and on your custom domain. If both hostnames are in use, keep them under one site in Rybbit so sessions are not split.
* **Post embeds**: custom HTML embedded inside a post is scoped to that post. Put the snippet in head code snippets, not in a post.
* **Nothing tracked while logged in as admin**: Circle applies head code to admins too, so check that your own IP or user is not excluded in Rybbit's site settings before assuming the snippet is missing.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ClickFunnels (/fr/docs/guides/clickfunnels)





ClickFunnels 2.0 has a **Header Code** field at three levels: **Site Settings** for the whole workspace, **Funnel settings** for every page in one funnel, and the page editor for a single page. Add the snippet at the widest level you want tracked and leave the narrower ones empty so it is not loaded twice.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ClickFunnels [#add-the-snippet-to-clickfunnels]

    <Tabs items="[&#x22;Whole site&#x22;, &#x22;One funnel&#x22;, &#x22;One page&#x22;]">
      <Tab>
        1. In your workspace, open the **Site & Blog** app in the left menu and click **Site Settings**.
        2. Paste the snippet into **Header Code**.
        3. Save.

        This applies to every page in the workspace: funnel pages, store pages, courses, blog posts and site pages.
      </Tab>

      <Tab>
        1. Open **Funnels** and click the **Settings** gear next to the funnel (or the **Settings** button in the top-right of the funnel workflow editor).
        2. Paste the snippet into **Head Code**.
        3. Click **Update Funnel**.

        The code loads on every page of that funnel only.
      </Tab>

      <Tab>
        1. Open the page in the page editor.
        2. Go to **Settings > Tracking Code** and paste the snippet into **Header Code**.
        3. Click **Save**.

        The code loads on this page only.
      </Tab>
    </Tabs>

    Save, then open the live page URL to test: header code does not run inside the page editor.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Duplicate pageviews**: the snippet is present at more than one level (site and funnel, or funnel and page). Keep a single copy.
* **Snippet not in the page source**: check which level you pasted it at. Site Settings covers the workspace, funnel settings cover that funnel's pages only, and the page editor covers one page.
* **jQuery**: ClickFunnels pages already include jQuery, so do not load it again in the same header code block; a second copy can break page scripts.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Contentful (/fr/docs/guides/contentful)





Contentful is a headless CMS: it stores content and delivers it over its APIs, but never renders your pages. The tracking snippet therefore goes into the frontend that consumes Contentful, not into Contentful itself.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Contentful [#add-the-snippet-to-contentful]

    <Callout type="info">
      Contentful has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Contentful.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Contentful frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby), which pairs with the official `gatsby-source-contentful` plugin
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Editor previews count as visits**: Contentful's content preview URLs open a preview or draft build of your frontend. Register that deployment as a separate site in Rybbit, or leave the snippet out of preview builds, so editors' previews are not mixed into your production data.
* **The Contentful web app is not tracked**: the snippet only runs on your frontend, so time spent editing in Contentful never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Craft CMS (/fr/docs/guides/craft-cms)





Craft CMS renders pages from Twig templates in the `templates/` folder, so the snippet goes into the base template that your section templates extend. A fresh `craftcms/craft` project ships a single `templates/index.twig` containing the full HTML document; most projects move that boilerplate into a base template and `{% extends %}` it.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Craft CMS [#add-the-snippet-to-craft-cms]

    1. Open the template that owns your `<head>`. In a fresh install that is `templates/index.twig`; in a project with a base template it is the underscore-prefixed file every page extends, such as `templates/_layout.twig`.
    2. Add the tag before `</head>`:

    ```twig title="templates/_layout.twig"
    <!DOCTYPE html>
    <html lang="{{ currentSite.language }}">
    <head>
        <meta charset="utf-8">
        <title>{{ siteName }}</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        {% block content %}{% endblock %}
    </body>
    </html>
    ```

    3. Every section template that extends the base template now loads the script:

    ```twig title="templates/blog/_entry.twig"
    {% extends "_layout" %}

    {% block content %}
        <h1>{{ entry.title }}</h1>
        {{ entry.body }}
    {% endblock %}
    {% endraw %}
    ```

    To keep the site ID out of templates and vary it per environment, read it from `.env` with `{{ getenv('RYBBIT_SITE_ID') }}`, or store it in a Global Set and use `{{ settings.rybbitSiteId }}`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Template caching**: if you wrap the head in `{% cache %}` tags, the change appears only after the cache expires or you run `php craft clear-caches/all`.
* **Live Preview counts as visits**: the control panel's Live Preview renders your template in an iframe with `x-craft-live-preview` in the query string. Wrap the tag in `{% if not craft.app.request.isPreview %}` to leave editors' previews out of your data.
* **Control panel is not tracked**: `/admin` uses Craft's own templates, so the snippet never runs there.
* **Multiple base templates**: if some sections extend a different base (for example `_layout-landing.twig`), add the tag to each one, or move it into a partial and `{% include %}` it from every base.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Discourse (/fr/docs/guides/discourse)





Discourse adds site-wide code through **theme components**. A component has an editable `</head>` section that Discourse injects into every page and, because Discourse ships a strict Content Security Policy, it stamps the required nonce onto script tags placed there. No server access or plugin is needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Discourse [#add-the-snippet-to-discourse]

    1. In the admin sidebar open **Appearance → Themes and components** (older versions: **Admin → Customize → Themes**).
    2. On the **Components** tab click **Install**, choose **Create new**, name it "Rybbit Analytics", make sure the type is **Component** and click **Create**.
    3. Click **Edit CSS/HTML**, stay on the **Common*&#x2A; tab and open the &#x2A;*`</head>`** section (not **Header**, which is the visible page header).
    4. Paste the snippet and click **Save**.
    5. Back on the component page, add your active theme under **Include component on these themes** so the component is enabled.

    Discourse is a single-page app: after the first load, topics and categories open without a full page reload. The tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`, so those navigations are recorded as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Component saved but the script is missing from the page source**: the component is not attached to the active theme. Add the theme under **Include component on these themes**, or add the component from the theme's **Included components** list.
* **Script tag present but blocked**: check the browser console for a CSP error. Scripts added through the `</head>` section receive Discourse's nonce automatically; scripts injected any other way (for example from a plugin's raw HTML) do not.
* **Only the first pageview is recorded**: the **SPA Navigation** setting is off for the site in your Rybbit dashboard. Turn it on under Site Settings.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Django (/fr/docs/guides/django)





Django pages extend a base template, so the snippet goes into the `<head>` of that base template. Put the site ID in `settings.py`, read from an environment variable, and pass it to templates with a small context processor so no template hard-codes the ID.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Django [#add-the-snippet-to-django]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to `settings.py`, reading from the environment:

    ```python filename="settings.py"
    import os

    RYBBIT_INSTANCE_URL = os.environ.get("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
    RYBBIT_SITE_ID = os.environ.get("RYBBIT_SITE_ID", "")
    ```

    Set `RYBBIT_SITE_ID=YOUR_SITE_ID` in your production environment (or your `.env` file if you load one with django-environ or python-dotenv).

    #### Expose the values to templates [#expose-the-values-to-templates]

    Create a context processor that adds both settings to every template context:

    ```python filename="myproject/context_processors.py"
    from django.conf import settings


    def rybbit(request):
        return {
            "RYBBIT_INSTANCE_URL": settings.RYBBIT_INSTANCE_URL,
            "RYBBIT_SITE_ID": settings.RYBBIT_SITE_ID,
        }
    ```

    Register it under `TEMPLATES` in `settings.py`:

    ```python filename="settings.py"
    TEMPLATES = [
        {
            "BACKEND": "django.template.backends.django.DjangoTemplates",
            "DIRS": [BASE_DIR / "templates"],
            "APP_DIRS": True,
            "OPTIONS": {
                "context_processors": [
                    "django.template.context_processors.request",
                    "django.contrib.auth.context_processors.auth",
                    "django.contrib.messages.context_processors.messages",
                    "myproject.context_processors.rybbit",
                ],
            },
        },
    ]
    ```

    #### Add the tag to your base template [#add-the-tag-to-your-base-template]

    Open the template that every page extends, usually `templates/base.html`, and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My Site{% endblock %}</title>

        {% if RYBBIT_SITE_ID %}
        <script src="{{ RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ RYBBIT_SITE_ID }}" defer></script>
        {% endif %}
    </head>
    ```

    The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable.

    Pages that do not `{% extends "base.html" %}` (for example a separate admin or landing template) need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: settings are read at startup, so restart the server (or your WSGI/ASGI workers) after changing `RYBBIT_SITE_ID`. Confirm the context processor path matches your project package name.
* **Template rendered without a request**: context processors only run for templates rendered with a `RequestContext`, which `render()` and class-based views provide. `Template.render()` without a request has no `RYBBIT_SITE_ID` and the guard hides the tag.
* **Content Security Policy**: if you use django-csp, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Docusaurus (/fr/docs/guides/docusaurus)





Docusaurus has a `scripts` option in `docusaurus.config.js` that adds a `<script>` tag to the `<head>` of every page, so no theme swizzling is needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Docusaurus [#add-the-snippet-to-docusaurus]

    Open `docusaurus.config.js` (or `docusaurus.config.ts`) at the root of your project and add the script to the `scripts` array:

    ```javascript filename="docusaurus.config.js"
    /** @type {import('@docusaurus/types').Config} */
    const config = {
      // ... title, url, baseUrl, presets, themeConfig

      scripts: [
        {
          src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
          defer: true,
        },
      ],
    };

    module.exports = config;
    ```

    If you already manage tags through `headTags`, this form is equivalent:

    ```javascript filename="docusaurus.config.js"
    headTags: [
      {
        tagName: "script",
        attributes: {
          src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
          defer: "true",
        },
      },
    ],
    ```

    Rebuild with `npm run build` and deploy. The tag is not hot-reloaded into a running `npm run start` session until you restart it.

    <Callout type="info">
      Docusaurus builds a single-page app on React Router. Rybbit detects client-side route changes and records them as pageviews, so no extra code is needed for navigation.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Docusaurus pages are React, so you can fire events from a component and use it in MDX:

```jsx filename="src/components/TrackedButton.jsx"
import React from "react";

export default function TrackedButton({ children, eventName, eventData }) {
  const handleClick = () => {
    window.rybbit?.event(eventName, eventData);
  };

  return (
    <button onClick={handleClick} className="button button--primary">
      {children}
    </button>
  );
}
```

```mdx
import TrackedButton from "@site/src/components/TrackedButton";

<TrackedButton eventName="learn_more_clicked" eventData={{ page: "introduction" }}>
  Learn more
</TrackedButton>
```

For site-wide listeners, use a [client module](https://docusaurus.io/docs/advanced/client-modules). `onRouteDidUpdate` runs after every navigation once the DOM is ready:

```javascript filename="src/client-modules/rybbit-events.js"
export function onRouteDidUpdate() {
  document.querySelectorAll('a[target="_blank"]').forEach((link) => {
    link.addEventListener("click", () => {
      window.rybbit?.event("external_link_click", { href: link.href });
    });
  });
}
```

Register it in `docusaurus.config.js` under `clientModules: [require.resolve("./src/client-modules/rybbit-events.js")]`. Client modules also run during server-side rendering, so guard any `window` access.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Drupal (/fr/docs/guides/drupal)





The [Rybbit module](https://www.drupal.org/project/rybbit) on Drupal.org adds the tracking script to every page and can pass logged-in user details to Rybbit, so you enter a Site ID instead of editing your theme. It requires Drupal 10.3 or later.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Drupal [#add-the-snippet-to-drupal]

    <Tabs items="[&#x22;Rybbit module&#x22;, &#x22;Theme template&#x22;]">
      <Tab>
        1. Install and enable the module:

           ```bash
           composer require drupal/rybbit
           drush en rybbit
           ```

        2. Go to **Configuration → Web services → Rybbit analytics** (`/admin/config/services/rybbit`). Your account needs the *administer rybbit* permission.

        3. Enter your **Site ID** and save.

        Optional settings on the same page:

        * **Script URL**: defaults to Rybbit cloud. Point it at your own instance if you self-host Rybbit.
        * **Visibility**: restrict tracking by role or by page path, each in include or exclude mode.
        * **Identify logged-in users**: calls `identify()` with the user's UUID by default, and sends traits you define as key/value pairs. `username`, `name` and `email` are recognised trait names.
        * The module also exposes hooks for altering the sitewide and per-user tracking data from your own module.
      </Tab>

      <Tab>
        If you cannot install contributed modules, copy `core/modules/system/templates/html.html.twig` into your theme's `templates` folder and add the snippet just before `</head>`:

        ```twig
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Clear caches afterwards so Drupal picks up the new template.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Script missing after saving settings**: pages are served from Drupal's page cache. Clear caches with `drush cr` or **Configuration → Development → Performance → Clear all caches**.
* **Visitors are tracked but you are not**: check the role and path visibility settings on the module page. Excluding the administrator role is a common setup.
* **Logged-in users appear anonymous**: enable **Identify logged-in users** in the module settings; without it Drupal accounts are tracked like any other visitor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Duda (/fr/docs/guides/duda)





Duda has a site-wide **Header HTML** panel in the site settings with two fields: **Head HTML**, printed inside `<head>` on every page, and **Body End HTML**, printed before `</body>`. The snippet goes into Head HTML, and the site must be republished for it to reach the live site.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Duda [#add-the-snippet-to-duda]

    1. In the editor's side panel, click **More**, then **Settings**.
    2. Click **Header HTML**.
    3. Paste the snippet into **Head HTML** and click **Save**.
    4. **Republish** the site. Saved header code shows in the editor and preview, but the live site is only updated on republish.

    Head HTML accepts `<script>`, `<link>` and `<meta>` tags; anything else is stripped on save. The tracking snippet is a single `<script>` tag, so it is kept.

    To limit tracking to one page instead, open that page's **settings** (gear icon), click **SEO** and paste the snippet into that page's **Header HTML**.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the live page source**: the site was not republished. Republish after every change to Header HTML.
* **Code disappears after saving**: Head HTML strips tags other than `<script>`, `<link>` and `<meta>`. Paste only the script tag, without wrapping HTML or comments.
* **Consent management app in use**: Duda loads Head HTML before consent banners can intercept it. If you need the tracker gated by consent, put the snippet in **Body End HTML** instead, where the consent app can control it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ecwid (/fr/docs/guides/ecwid)





An Ecwid by Lightspeed store runs either on Ecwid's hosted **Instant Site** or embedded in a page on another platform. On Instant Site the snippet goes into the site's header code setting; for an embedded store it goes into the `<head>` of the host site, and the storefront Ecwid renders inside that page is tracked with it.

<Callout type="warn">
  Custom code on Instant Site is available on the **Venture**, **Business** and **Unlimited** plans. The free Starter plan has no custom code fields.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ecwid [#add-the-snippet-to-ecwid]

    <Tabs items="[&#x22;Instant Site&#x22;, &#x22;Embedded store&#x22;]">
      <Tab>
        1. From your Ecwid admin, go to **Website** (or **Overview → Manage Instant Site**).
        2. Scroll down to **SEO settings** and click **Add Code** under **Header meta tags and site verification**.
        3. Paste the snippet and save.
        4. Reload your Instant Site in the browser; there is no separate publish step for this setting.

        The **Custom JavaScript code** field under **Advanced website settings** on the same page also works, but it prints code at the end of `<body>`, so prefer the header field.
      </Tab>

      <Tab>
        The store is rendered by Ecwid's embed script inside your own page, so add the snippet to the `<head>` of the host site with that platform's method. See the [integration guides](/docs/guides) for WordPress, Wix, Squarespace, Webflow and others.

        One snippet covers the whole store: product pages, cart and checkout all render inside the same host page.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Ecwid's storefront JavaScript API fires `Ecwid.OnOrderPlaced` with the order right after a customer places it. Add this where the `Ecwid` object already exists: on Instant Site, under **Advanced website settings → Custom JavaScript code**; on an embedded store, after the Ecwid embed script on the host page.

```html
<script>
Ecwid.OnAPILoaded.add(function () {
  Ecwid.OnOrderPlaced.add(function (order) {
    window.rybbit.event('purchase', {
      transaction_id: order.vendorNumber,
      value: order.total,
      tax: order.tax,
      shipping: order.shipping,
      items: order.items.map(function (item) {
        return { item_id: item.sku, item_name: item.name, price: item.price, quantity: item.quantity };
      })
    });
  });
});
</script>
```

`vendorNumber` is the order number customers see in emails; `orderNumber` is Ecwid's internal ID. Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.

Ecwid also has a **Custom tracking code on Order Confirmation page** field under **Settings → General → Tracking & Analytics** (same plans as above). Code there runs on the `/checkout/order-confirmation` page and can use Ecwid's template variables when wrapped in `<#noescape>`:

```html
<script>
<#noescape>
document.addEventListener('DOMContentLoaded', function () {
  window.rybbit.event('purchase', { transaction_id: "${order.number}", value: ${order.total} });
});
</#noescape>
</script>
```

Use one method or the other, not both, or every order is counted twice.

## Troubleshooting [#troubleshooting]

* **No Add Code button under SEO settings**: the store is on the Starter plan. Custom code needs Venture or higher.
* **`Ecwid is not defined`**: the purchase snippet ran before Ecwid's script. Move it below the embed script, or keep it in the Instant Site **Custom JavaScript code** field, which runs at the end of the page.
* **Embedded store, no pageviews**: the snippet belongs to the host site, not to Ecwid. Check the host page's source for `script.js?siteId=`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Electron (/fr/docs/guides/electron)





An Electron renderer is a Chromium page, so Rybbit runs in it the same way it runs in a browser. For a renderer built with a bundler (Vite, webpack, the Electron Forge templates) install the `@rybbit/js` SDK and initialise it in the renderer entry file; for a plain HTML renderer put the snippet in the `<head>` of the HTML file the window loads. In both cases allow `https://app.rybbit.io` in the renderer's Content Security Policy.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Electron [#add-the-snippet-to-electron]

    <Tabs items="[&#x22;@rybbit/js SDK&#x22;, &#x22;Script tag&#x22;]">
      <Tab>
        The SDK is bundled with your renderer code, so nothing is loaded from a CDN at runtime and `script-src 'self'` stays intact.

        1. Install the package in your project:

        ```bash
        npm install @rybbit/js
        ```

        2. Initialise it once in the renderer entry file, before any other tracking call:

        ```js title="src/renderer.js"
        import rybbit from "@rybbit/js";

        await rybbit.init({
          analyticsHost: "https://app.rybbit.io/api",
          siteId: "YOUR_SITE_ID",
        });
        ```

        3. Allow the analytics host in `connect-src`. Electron recommends a CSP for every renderer; when the renderer is loaded from a file, HTTP headers are not available, so use the meta tag:

        ```html title="src/index.html"
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'self'; connect-src 'self' https://app.rybbit.io"
        />
        ```
      </Tab>

      <Tab>
        Paste the snippet into the `<head>` of the renderer HTML and allow the host in both `script-src` (the script itself) and `connect-src` (its requests):

        ```html title="src/index.html"
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'self'; script-src 'self' https://app.rybbit.io; connect-src 'self' https://app.rybbit.io"
        />
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        If you set the CSP from the main process with `session.defaultSession.webRequest.onHeadersReceived` instead, add the same two sources there.
      </Tab>
    </Tabs>

    Both methods track in-app navigation without extra code: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so history-mode and hash-mode routers are covered.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Requests are blocked on the `file://` origin**: Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only. A renderer opened with `win.loadFile()` runs on the `file://` origin and sends `Origin: null`, so Chromium blocks the `POST` to `/api/track` before it leaves the app. The same applies to custom schemes registered with `protocol.handle()`. Load the renderer over http(s) with `win.loadURL()` (your dev server in development, a hosted or locally served build in production) and tracking works.
* **Console shows a CSP violation**: the message names the directive that blocked the request. Add `https://app.rybbit.io` to that directive; `connect-src` covers the SDK, and the script tag also needs `script-src`.
* **Hostname is empty in the dashboard**: pageviews report the renderer's `window.location.hostname`, which is empty for `file://` pages. Filter by site rather than hostname.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Eleventy (/fr/docs/guides/eleventy)





Eleventy renders every page through a layout in `_includes/`, so the snippet goes in your base layout's `<head>`. Keep the site ID in a global data file under `_data/` so the layout stays free of hard-coded values.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Eleventy [#add-the-snippet-to-eleventy]

    1. Create `_data/rybbit.json` (create the `_data/` directory if it does not exist). Every template can then read it as `rybbit`. Change `instanceUrl` only if you self-host:

       ```json title="_data/rybbit.json"
       {
         "siteId": "YOUR_SITE_ID",
         "instanceUrl": "https://app.rybbit.io"
       }
       ```

    2. Open your base layout and add the tag inside `<head>`. The `eleventy.env.runMode` check keeps the script out of `--serve` and `--watch` runs, so local development is not tracked; the `rybbit.siteId` check keeps it out of builds with no ID configured.

    <Tabs items="[&#x22;Nunjucks&#x22;, &#x22;Liquid&#x22;]">
      <Tab value="Nunjucks">
        ```html title="_includes/base.njk"
        <head>
          ...
          {% if eleventy.env.runMode == "build" and rybbit.siteId %}
            <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>

      <Tab value="Liquid">
        ```html title="_includes/base.liquid"
        <head>
          ...
          {% if eleventy.env.runMode == "build" and rybbit.siteId %}
            <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>
    </Tabs>

    3. Build and deploy the generated `_site/` directory:

       ```bash
       npx @11ty/eleventy
       ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `npx @11ty/eleventy --serve` sets `runMode` to `serve`, so the guard removes the tag. Check the output of a plain build instead.
* **Eleventy 1.x**: `eleventy.env.runMode` was added in Eleventy 2.0. On older versions drop the `runMode` condition and keep only the `rybbit.siteId` check.
* **Custom data directory**: if your config sets `dir.data`, put `rybbit.json` in that directory instead of `_data/`.
* **Several layouts**: a page only gets the tag if its layout chain ends in the layout you edited. Pages with `layout: none` or a different base layout need the tag added there too.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ember (/fr/docs/guides/ember)





An Ember app has one HTML shell that every route renders into. Apps created with the current Vite-based `ember new` blueprint keep it at `index.html` in the project root; classic ember-cli apps keep it at `app/index.html`. Paste the snippet into the `<head>` of that file.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ember [#add-the-snippet-to-ember]

    Open `index.html` (or `app/index.html` in a classic ember-cli app) and paste the snippet inside `<head>`, after the `{{content-for "head"}}` placeholder:

    ```handlebars title="index.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8">
        <title>MyApp</title>
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        {{content-for "head"}}

        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

        <link integrity="" rel="stylesheet" href="/@embroider/virtual/vendor.css">
        <link integrity="" rel="stylesheet" href="/@embroider/virtual/app.css">

        {{content-for "head-footer"}}
      </head>
      <body>
        {{content-for "body"}}
        ...
        {{content-for "body-footer"}}
      </body>
    </html>
    ```

    Keep the `{{content-for}}` placeholders in place; the build fills them in. Route transitions made by Ember's router (the default `history` location type) are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a component action. Guard the call so a blocked or still-loading script does not throw.

```js title="app/components/signup-button.gjs"
import Component from "@glimmer/component";
import { on } from "@ember/modifier";

export default class SignupButton extends Component {
  trackSignup = () => {
    if (window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  <template>
    <button type="button" {{on "click" this.trackSignup}}>Sign up</button>
  </template>
}
```

## Troubleshooting [#troubleshooting]

* **`index.html` is also used by the test runner**: `tests/index.html` is a separate file. Do not add the snippet there, or test runs send pageviews to your dashboard.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# FastAPI (/fr/docs/guides/fastapi)





FastAPI serves HTML through `Jinja2Templates`, so the snippet goes into the `<head>` of the base template your pages extend. Keep the site ID in a `pydantic-settings` class and register it as a Jinja global so every template can render the tag without passing it through each route.

<Callout type="info">
  The tracking script runs in a browser, so it only applies to routes that return template-rendered HTML. JSON endpoints have nothing for it to track.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to FastAPI [#add-the-snippet-to-fastapi]

    #### Configure the site ID [#configure-the-site-id]

    Install `pydantic-settings` and `jinja2` if you have not already:

    ```bash
    pip install pydantic-settings jinja2
    ```

    Define the settings, reading from the environment and an optional `.env` file:

    ```python filename="config.py"
    from pydantic_settings import BaseSettings, SettingsConfigDict


    class Settings(BaseSettings):
        model_config = SettingsConfigDict(env_file=".env")

        rybbit_instance_url: str = "https://app.rybbit.io"
        rybbit_site_id: str = ""


    settings = Settings()
    ```

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    #### Register the values with Jinja [#register-the-values-with-jinja]

    `Jinja2Templates` exposes its environment as `templates.env`, so add the settings as globals once, next to where you create the templates object:

    ```python filename="main.py"
    from fastapi import FastAPI, Request
    from fastapi.responses import HTMLResponse
    from fastapi.templating import Jinja2Templates

    from config import settings

    app = FastAPI()
    templates = Jinja2Templates(directory="templates")
    templates.env.globals["rybbit_instance_url"] = settings.rybbit_instance_url
    templates.env.globals["rybbit_site_id"] = settings.rybbit_site_id


    @app.get("/", response_class=HTMLResponse)
    async def index(request: Request):
        return templates.TemplateResponse(request=request, name="index.html")
    ```

    #### Add the tag to your base template [#add-the-tag-to-your-base-template]

    Open the template your pages extend, usually `templates/base.html`, and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My App{% endblock %}</title>

        {% if rybbit_site_id %}
        <script src="{{ rybbit_instance_url }}/api/script.js?siteId={{ rybbit_site_id }}" defer></script>
        {% endif %}
    </head>
    ```

    The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable. Templates that do not extend the base need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `Settings()` reads the environment when the module is imported, so restart Uvicorn (or your process manager) after changing `RYBBIT_SITE_ID`.
* **Several `Jinja2Templates` instances**: globals are per environment. If routers create their own `Jinja2Templates`, set the globals on each, or share one instance from a module.
* **Content Security Policy**: if middleware sets one, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Flask (/fr/docs/guides/flask)





Flask renders Jinja templates, and most apps extend a shared base layout, so the snippet goes into that layout's `<head>`. Flask exposes `app.config` to every template as `config`, so store the site ID there and reference it from the template.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Flask [#add-the-snippet-to-flask]

    #### Configure the site ID [#configure-the-site-id]

    Flask loads any environment variable prefixed with `FLASK_` into `app.config` when you call `from_prefixed_env()`. Set the values in your environment (`flask run` also reads a `.env` file when python-dotenv is installed):

    ```bash filename=".env"
    FLASK_RYBBIT_INSTANCE_URL=https://app.rybbit.io
    FLASK_RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then load them where you create the app:

    ```python filename="app.py"
    from flask import Flask, render_template

    app = Flask(__name__)
    app.config.setdefault("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
    app.config.from_prefixed_env()


    @app.route("/")
    def index():
        return render_template("index.html")
    ```

    `from_prefixed_env()` parses values as JSON where it can, so a numeric site ID arrives as an `int`. It renders the same in the template.

    If you keep configuration in a Python file or class instead, add `RYBBIT_INSTANCE_URL` and `RYBBIT_SITE_ID` there and load it with `app.config.from_object()`.

    #### Add the tag to your base layout [#add-the-tag-to-your-base-layout]

    Open the template that your pages extend, usually `templates/base.html` (or `templates/layout.html`), and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My App{% endblock %}</title>

        {% if config.RYBBIT_SITE_ID %}
        <script src="{{ config.RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ config.RYBBIT_SITE_ID }}" defer></script>
        {% endif %}
    </head>
    ```

    `config` is part of Flask's standard template context, so no context processor is needed. The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is unset, so local development is not tracked unless you set the variable.

    Templates that do not extend the base layout need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `from_prefixed_env()` reads the environment when the app is created, so restart the server after changing `FLASK_RYBBIT_SITE_ID`. Check `app.config["RYBBIT_SITE_ID"]` in `flask shell`.
* **Macros imported into other templates**: `config` is added to the render context, not to imported templates. A macro that outputs the tag must be imported `with context`.
* **Content Security Policy**: if you set one with Flask-Talisman or similar, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `FLASK_RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Flutter web (/fr/docs/guides/flutter-web)





A Flutter web app is served from the `web/index.html` template in your project, which `flutter build web` copies to `build/web/index.html`. The snippet goes in that file's `<head>`. Flutter draws the UI into a canvas rather than DOM elements, so pageviews and manual events work as usual while anything that inspects the DOM does not.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Flutter web [#add-the-snippet-to-flutter-web]

    1. Open `web/index.html` in your Flutter project.
    2. Paste the snippet inside `<head>`, above the `flutter_bootstrap.js` script that Flutter generates:

    ```html title="web/index.html"
    <head>
      <meta charset="UTF-8" />
      <title>My App</title>
      <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    ```

    3. Rebuild with `flutter build web` and deploy the `build/web` folder.

    Navigation is tracked automatically with either URL strategy. Flutter's default hash strategy writes routes as `/#/settings`, and the tracker listens for `hashchange` and records `#/settings` as the path `/settings`. With `usePathUrlStrategy()` the Navigator uses the History API, and the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Flutter widgets are not HTML elements, so `data-rybbit-event` attributes have nothing to attach to. Call `window.rybbit.event()` from Dart through `dart:js_interop` instead:

```dart title="lib/analytics.dart"
import 'dart:js_interop';

@JS('rybbit.event')
external void _rybbitEvent(String name, [JSAny? properties]);

void trackEvent(String name, [Map<String, Object?>? properties]) {
  _rybbitEvent(name, properties?.jsify());
}
```

```dart
ElevatedButton(
  onPressed: () {
    trackEvent('signup_click', {'plan': 'pro'});
  },
  child: const Text('Sign up'),
)
```

Guard the call with `kIsWeb` if the same code also compiles for mobile or desktop targets.

## Troubleshooting [#troubleshooting]

* **Clicks, outbound links and session replay show nothing**: the CanvasKit and Skwasm renderers paint into a single `<canvas>`, so DOM-based features (`data-rybbit-event` attributes, outbound-link tracking, button-click autocapture, session replay) have no elements to observe. Use the Dart interop above for events.
* **Deep links 404 after switching to `usePathUrlStrategy()`**: path URLs need the web server to rewrite every route to `index.html`; the Flutter dev server does this for you, production hosting must be configured.
* **`rybbit` is undefined in Dart**: the snippet is `defer`red, so it is not ready during `main()`. Send events from user interactions, not from app start-up.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Framer (/fr/docs/guides/framer)





Framer has a **Custom Code** section in the site settings that injects HTML into the `<head>` of every published page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Framer [#add-the-snippet-to-framer]

    1. Open your Framer project and go to **Site Settings → General**.
    2. Scroll to **Custom Code**.
    3. Paste the snippet into the **Start of `<head>` tag** field (End of `<head>` works too).
    4. Click **Save**, then **Publish**. Custom code only reaches the live site on publish.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Use a **Code Override** to send events from any element in the canvas.

1. Select the element, open **Overrides*&#x2A; in the properties panel, and click **+ File** to create an override file such as `RybbitOverrides.tsx`.
2. Add an override that wraps the element's click handler:

```tsx
// RybbitOverrides.tsx
import type { ComponentType } from "react";

export function withRybbitClick(Component: ComponentType): ComponentType {
  return (props) => {
    const handleClick = () => {
      window.rybbit?.event("cta_click", { label: props.text ?? "cta" });
      props.onClick?.();
    };
    return <Component {...props} onClick={handleClick} />;
  };
}
```

3. Back in the properties panel, pick the file and apply `withRybbitClick` to the element.

The same `window.rybbit.event()` call works inside a **Code Component**.

## Troubleshooting [#troubleshooting]

* **Navigation between pages is not tracked**: Framer sites navigate client-side and the script detects those URL changes. If a view changes without the URL changing, call `window.rybbit.pageview()` from an override when it appears.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Fumadocs (/fr/docs/guides/fumadocs)





Fumadocs is a documentation framework for Next.js, so the snippet goes in the root layout, `app/layout.tsx`, rendered with `next/script` so it is on every page including the docs routes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Fumadocs [#add-the-snippet-to-fumadocs]

    Open `app/layout.tsx` and render the `Script` component inside `<body>`, next to the `RootProvider` that Fumadocs already puts there:

    ```tsx title="app/layout.tsx"
    import { RootProvider } from "fumadocs-ui/provider/next";
    import Script from "next/script";
    import type { ReactNode } from "react";

    export default function Layout({ children }: { children: ReactNode }) {
      return (
        <html lang="en" suppressHydrationWarning>
          <body className="flex flex-col min-h-screen">
            <RootProvider>{children}</RootProvider>
            <Script
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    Use the root layout, not `app/docs/layout.tsx`: the docs layout only wraps pages under `/docs`, so a landing page outside it would be missed.

    Client-side navigation between docs pages is recorded as pageviews automatically. The [Next.js guide](/docs/guides/react/next-js) covers the `Script` component, custom events from client components and proxying through your own domain.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ghost (/fr/docs/guides/ghost)





Ghost has a built-in **Code injection** setting that adds HTML to the `<head>` of every page, so no theme edits are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ghost [#add-the-snippet-to-ghost]

    1. Open **Ghost Admin** and click the **Settings** gear in the bottom left.
    2. Under **Advanced**, open **Code injection**.
    3. Paste the snippet into **Site header** and click **Save**.

    If you maintain your own theme instead, add the snippet to `default.hbs` just before `</head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Ghost(Pro) with a custom theme**: code injection still applies on top of the theme, so prefer it over editing `default.hbs`.
* **Member-only content**: pages behind the paywall are tracked like any other page for visitors who can view them.
* **Portal and newsletter previews** render in an iframe and are not tracked.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# GitBook (/fr/docs/guides/gitbook)





GitBook does not let you add custom scripts to a published site, and its integration platform does not let third parties inject them either. This page explains what that means and what your options are.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to GitBook [#add-the-snippet-to-gitbook]

    <Callout type="warn">
      There is currently no supported way to load the Rybbit snippet on a GitBook-hosted site. The old **Custom scripts → Head** setting was removed, and GitBook's [integration scopes](https://gitbook.com/docs/developers/integrations/configurations) reserve `site:script:inject` for GitBook's own integrations: "Building integrations that inject JavaScript into a site or space is not possible at this time."
    </Callout>

    Your options:

    * **Use GitBook's built-in analytics.** The **Insights** section in the GitBook app reports page views and search terms for published sites without any script.
    * **Wait for a native integration.** A Rybbit integration would need GitBook to build or approve it. Ask GitBook support for it, and watch the [Rybbit roadmap](/docs/roadmap).
    * **Host the docs elsewhere.** [Docusaurus](/docs/guides/docusaurus), [Mintlify](/docs/guides/mintlify), [VitePress](/docs/guides/vitepress), [Starlight](/docs/guides/starlight) and [Fumadocs](/docs/guides/fumadocs) all take the snippet directly, and GitBook can export a space as Markdown to migrate.

    The rest of your site (marketing pages, app, blog) is unaffected: add the snippet there as usual so traffic from the docs is still attributed by referrer.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Google Tag Manager (/fr/docs/guides/google-tag-manager)





Google Tag Manager loads Rybbit through a **Custom HTML** tag fired on **All Pages**, so nothing in your site's code changes. Events you already push to the `dataLayer` can be forwarded to Rybbit with a second tag.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Google Tag Manager [#add-the-snippet-to-google-tag-manager]

    1. Open your GTM container and go to **Tags → New**.
    2. Under **Tag Configuration**, choose **Custom HTML** and paste the snippet:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    3. Under **Triggering**, choose **All Pages** (the built-in Page View trigger).
    4. Name the tag, for example `Rybbit - Loader`, and click **Save**.
    5. Click **Submit** and publish the container version.

    <Callout type="warn">
      GTM rebuilds Custom HTML tags before injecting them and can drop non-standard attributes. Keep the site ID in the URL (`?siteId=`) as shown; the older `data-*` attribute form is not reliable here.
    </Callout>

    Use **Preview** mode to confirm the tag fires on page load before publishing.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Once the loader tag is published, `window.rybbit` is available to your own JavaScript and to other GTM tags.

#### Forward dataLayer events [#forward-datalayer-events]

If your site already pushes events like `dataLayer.push({ event: "signup" })`, one tag can forward them to Rybbit:

1. Create a **Custom Event** trigger. Set the event name to a regex such as `signup|purchase|add_to_cart` (tick **Use regex matching**).
2. Create a **Custom HTML** tag with that trigger:

```html
<script>
  if (window.rybbit) {
    window.rybbit.event("{{Event}}", {
      page: "{{Page Path}}",
      referrer: "{{Referrer}}"
    });
  }
</script>
```

`{{Event}}`, `{{Page Path}}` and `{{Referrer}}` are GTM built-in variables. Add a **Data Layer Variable** for any custom field you push (for example `plan`) and reference it the same way.

#### Use GTM's click and form triggers [#use-gtms-click-and-form-triggers]

The same pattern works with built-in **Click** and **Form Submission** triggers:

```html
<script>
  if (window.rybbit) {
    window.rybbit.event("cta_clicked", {
      text: "{{Click Text}}",
      url: "{{Click URL}}"
    });
  }
</script>
```

Enable the **Click Text** and **Click URL** built-in variables under **Variables → Configure**.

## Troubleshooting [#troubleshooting]

* **Event tag fires before Rybbit loads**: the loader script is deferred, so an event tag on the same page load may run first and hit the `if (window.rybbit)` guard. Open the event tag's **Advanced Settings → Tag Sequencing** and set the loader tag to fire before it, or trigger the event tag on **Window Loaded** instead of **Page View**.
* **Consent mode**: if your container gates tags on consent, add the loader tag to the same consent group as your other analytics tags, otherwise it never fires.
* **Tag shows in Preview but not live**: the container version was not published. Click **Submit** and publish.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hexo (/fr/docs/guides/hexo)





Hexo 5 and later ship an injector API that adds HTML to the `<head>` of every generated page from a small file in your site's `scripts/` directory, so no theme edits are needed. Editing the theme's head partial is the fallback for older versions.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hexo [#add-the-snippet-to-hexo]

    <Tabs items="[&#x22;Injector script&#x22;, &#x22;Theme layout&#x22;]">
      <Tab value="Injector script">
        1. Add your site ID to the site `_config.yml` at the root of your project (not the theme config). `instance_url` is only needed if you self-host:

           ```yaml title="_config.yml"
           rybbit:
             site_id: "YOUR_SITE_ID"
             instance_url: "https://app.rybbit.io"
           ```

        2. Create `scripts/rybbit.js` (create the `scripts/` directory if it does not exist). Hexo loads every file in this directory at startup with the `hexo` object in scope:

           ```javascript title="scripts/rybbit.js"
           const { site_id: siteId, instance_url: instanceUrl = "https://app.rybbit.io" } =
             hexo.config.rybbit || {};

           if (siteId) {
             hexo.extend.injector.register(
               "head_end",
               `<script src="${instanceUrl}/api/script.js?siteId=${siteId}" defer></script>`
             );
           }
           ```

           `head_end` places the tag right before `</head>`. With no third argument the injector applies to every page type.
      </Tab>

      <Tab value="Theme layout">
        Open your theme's head partial and paste the snippet before `</head>`. For the default Landscape theme that file is `themes/landscape/layout/_partial/head.ejs`; other themes keep an equivalent partial under `layout/`.

        ```html title="themes/landscape/layout/_partial/head.ejs"
          ...
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Theme updates overwrite this file, so prefer the injector when your Hexo version supports it.
      </Tab>
    </Tabs>

    Regenerate and deploy the `public/` directory:

    ```bash
    hexo clean && hexo generate
    ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **`hexo.extend.injector` is undefined**: the injector API arrived in Hexo 5.0. Check `hexo version` and upgrade, or use the theme layout method.
* **Tag missing after adding the script**: run `hexo clean` before `hexo generate`; Hexo caches rendered output in `db.json` and can serve stale pages.
* **Local previews are tracked**: `hexo server` runs the same injector as `hexo generate`. Leave `site_id` empty in a local copy of `_config.yml`, or accept the local pageviews.
* **Theme config vs site config**: `hexo.config` reads the root `_config.yml`, not `themes/<name>/_config.yml`. Put the `rybbit` block in the root file.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hostinger Website Builder (/fr/docs/guides/hostinger)





Hostinger Website Builder has a **Custom code** integration in the website settings that adds code to every page. Script tags are placed at the end of `<body>` by default; a `data-render-head` attribute moves them into `<head>`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hostinger Website Builder [#add-the-snippet-to-hostinger-website-builder]

    1. Open your site in the builder and click &#x2A;*⋯** (More) at the top to open the website settings, then choose **Integrations**.
    2. Select **Custom code**.
    3. Paste the snippet with `data-render-head` added so it loads from `<head>`:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer data-render-head></script>
    ```

    4. Save the changes, then click **Update website** to publish. Custom code runs on the live site and in preview, not inside the editor.

    Without `data-render-head` the builder moves `<script>` tags to the end of `<body>`. The tracker still works there; the attribute only makes it load earlier.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **No requests to `script.js` in the editor**: expected. Integrations are injected into the published site only, so check the live URL or the preview.
* **Snippet saved but not in the page source**: the site was not updated after saving. Click **Update website**.
* **Site breaks after adding several snippets**: paste snippets one after another, never nested inside each other. If the page still fails, remove all custom code, update, and add the snippets back one at a time.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# htmx (/fr/docs/guides/htmx)





htmx pages are plain server-rendered HTML, so the snippet goes in the `<head>` of your base layout next to the htmx script tag, in whichever template your server uses for the full-page response.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to htmx [#add-the-snippet-to-htmx]

    Open the template that renders the full HTML document (the one that already loads htmx) and paste the snippet inside `<head>`:

    ```html title="layout.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My htmx App</title>
        <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.10/dist/htmx.min.js"></script>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <main id="content" hx-boost="true">...</main>
      </body>
    </html>
    ```

    Only full-page responses need the tag. Partial responses that htmx swaps into the page must not include it, or the script is re-evaluated on every swap.

    Navigations that htmx records in browser history are tracked automatically as pageviews: `hx-push-url` and `hx-boost` call `history.pushState()`, `hx-replace-url` calls `history.replaceState()`, and the back and forward buttons fire `popstate`. All three are hooked by the tracker. A swap without `hx-push-url` leaves the URL unchanged and is not counted as a pageview; send a [custom event](/docs/track-events) for those interactions instead.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Use the `data-rybbit-event` attribute on the element that triggers the request. The tracker listens for clicks on `document`, so it also works on content that htmx swapped in after the page loaded:

```html
<button
  hx-post="/subscribe"
  hx-target="#form"
  data-rybbit-event="newsletter_subscribe"
  data-rybbit-prop-plan="free"
>
  Subscribe
</button>
```

To record an event when the server has actually processed the request, listen for htmx's `htmx:afterRequest` event and call `window.rybbit.event()` from there.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# HubSpot (/fr/docs/guides/hubspot)





HubSpot Content Hub (formerly CMS Hub) has a **Site header HTML** setting that injects code into the `<head>` of every website page, landing page, blog post and knowledge base article on a domain, so no template edits are needed. Individual pages can add or override code from the content editor.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to HubSpot [#add-the-snippet-to-hubspot]

    <Tabs items="[&#x22;Site header HTML&#x22;, &#x22;Single page&#x22;]">
      <Tab>
        This adds the snippet to all HubSpot-hosted content on a domain.

        1. In your HubSpot account, click the **settings** icon in the top navigation bar.
        2. In the left sidebar, go to **Content > Pages**.
        3. Use the **Choose a domain to edit its settings** dropdown to pick the domain, or stay on the default settings to apply the code to every domain.
        4. Paste the snippet into the **Site header HTML** field.
        5. Click **Save**.

        If a domain has **Override default settings** turned on, the default header code no longer applies to it. Add the snippet to that domain's own settings as well.
      </Tab>

      <Tab>
        Use this to track a single page, or when someone else controls the domain settings.

        1. Open **Content > Website Pages** (or **Landing Pages**, **Blog**, **Knowledge Base**) and click the page name to open the editor.
        2. Click the **Settings** menu, then select **Advanced**.
        3. Under **Additional code snippets**, paste the snippet into the **Head HTML** field.
        4. Click **Update** or **Publish**.

        Per-page head HTML is added on top of the site header HTML, so a page tracked by both methods loads the script twice. Pick one.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

HubSpot forms submit inside the page without a full reload, so track them with a custom event. Add `data-rybbit-event` to a call-to-action button, or listen for HubSpot's form-submitted message in a small script placed after the snippet:

```html
<script>
  window.addEventListener("message", function (event) {
    if (event.data.type === "hsFormCallback" && event.data.eventName === "onFormSubmitted") {
      window.rybbit.event("form_submitted", { formId: event.data.id });
    }
  });
</script>
```

See [Track custom events](/docs/track-events) for the event API.

## Troubleshooting [#troubleshooting]

* **Snippet missing on one domain**: the site header HTML is per domain. Check whether that domain has **Override default settings** enabled and add the snippet there.
* **Duplicate pageviews**: the same page has the snippet in both site header HTML and its own **Head HTML**. Remove one.
* **Editor and preview**: the content editor renders pages in an iframe with unpublished changes. Previews are tracked like any other visit if they load the script, so avoid checking analytics from the editor.
* **Quotes**: header HTML set at the domain level also loads on HubSpot quotes hosted on that domain.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hugo (/fr/docs/guides/hugo)





Hugo builds every page from templates under `layouts/`, so the cleanest place for the snippet is a partial template that your base template includes on every page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hugo [#add-the-snippet-to-hugo]

    1. Add your site ID under `params` in your Hugo config (`hugo.toml`, or `config.toml` in older Hugo versions). `rybbitInstanceURL` is only needed if you self-host:

       ```toml title="hugo.toml"
       [params]
         rybbitSiteID = "YOUR_SITE_ID"
         rybbitInstanceURL = "https://app.rybbit.io"
       ```

    2. Create `layouts/partials/rybbit-analytics.html` (create the `layouts/partials/` directory if it does not exist):

       ```html title="layouts/partials/rybbit-analytics.html"
       {{ if and (not hugo.IsServer) .Site.Params.rybbitSiteID }}
         <script src="{{ .Site.Params.rybbitInstanceURL | default "https://app.rybbit.io" }}/api/script.js?siteId={{ .Site.Params.rybbitSiteID }}" defer></script>
       {{ end }}
       ```

       `not hugo.IsServer` skips the script during `hugo server`, so local development is not tracked. The `rybbitSiteID` check keeps the tag out of builds that have no ID configured.

    3. Include the partial from your base template, typically `layouts/_default/baseof.html`, inside `<head>`. If your theme owns `baseof.html`, copy it into your project's `layouts/_default/` first so the theme can be updated without losing the change; a theme footer partial such as `layouts/partials/footer.html` also works.

       ```html title="layouts/_default/baseof.html"
       <head>
         ...
         {{ partial "rybbit-analytics.html" . }}
       </head>
       ```

    4. Build with `hugo` and deploy the generated `public/` directory.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `hugo server` never emits it because of the `hugo.IsServer` guard. Check the output of a production `hugo` build instead.
* **Theme overrides**: a file at `layouts/_default/baseof.html` in your project takes precedence over the theme's copy, so make sure you edited the one Hugo actually renders.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Integration guides (/fr/docs/guides)



Rybbit works on any site that can load a script tag. Each guide below shows exactly where the tracking snippet goes on that platform and how to confirm it is working.

Don't see your platform? Paste the snippet from **Site Settings → Tracking Script** into the `<head>` of every page, or follow the [tracking script](/docs/script) reference.

<GuideIndex />


# Instapage (/fr/docs/guides/instapage)





Instapage takes custom scripts at two levels: **Workspace scripts** (under **Assets > Scripts**) apply to every page in a workspace, and each page also has its own **JavaScript** and **HTML/CSS** settings with a **Head** section. Custom HTML, CSS and JavaScript are included on all Instapage plans; Workspace scripts are limited to some subscriptions and show an upgrade prompt otherwise.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Instapage [#add-the-snippet-to-instapage]

    <Tabs items="[&#x22;Workspace scripts&#x22;, &#x22;Single page&#x22;]">
      <Tab>
        1. In the left menu, open **Assets**, then **Scripts**.
        2. Paste the snippet into the **Head** section.
        3. Above the editor, choose how it applies: option **A** adds it to every past and future page in the workspace; **B** leaves it off until you switch it on per page under **Scripts & Privacy**; **B + C** turns it on for all pages but lets you disable it per page.
        4. Click **Apply**.

        Workspace scripts load on the live URL before any page-level script, so the snippet is in place before other code on the page runs.
      </Tab>

      <Tab>
        1. Open the page in the builder and click **Settings** in the right sidebar.
        2. Open the **HTML/CSS** tab and paste the snippet into **Head**. (The **JavaScript** tab has the same three sections and wraps your code in `<script>` tags automatically; the snippet already has its own tag, so HTML/CSS is the simpler choice.)
        3. **Publish** the page. Custom code runs only on the live, published page, not in the editor or preview.
      </Tab>
    </Tabs>

    <Callout type="info">
      If you use Instapage's privacy compliance banner, put the snippet in the page's **Scripts & Privacy** section instead so it fires only after the visitor accepts.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: the page was saved but not republished. Custom code only reaches the live URL on publish.
* **Assets > Scripts shows an upgrade prompt**: Workspace scripts are not on your subscription. Add the snippet per page instead.
* **Duplicate pageviews**: the snippet is both a workspace script and a page-level script. Keep one copy.
* **Old version still served**: clear your browser cache after publishing; Instapage notes cached copies can outlive an update.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Jekyll (/fr/docs/guides/jekyll)





Jekyll renders every page through a layout, usually `_layouts/default.html`. Put the snippet in an include file that the layout pulls in, or paste it into the layout directly.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Jekyll [#add-the-snippet-to-jekyll]

    <Tabs items="[&#x22;Include file&#x22;, &#x22;Layout file&#x22;]">
      <Tab value="Include file">
        1. Add your site ID to `_config.yml`. `rybbit_instance_url` is only needed if you self-host:

           ```yaml title="_config.yml"
           rybbit_site_id: "YOUR_SITE_ID"
           rybbit_instance_url: "https://app.rybbit.io"
           ```

        2. Create `_includes/rybbit-analytics.html` (create the `_includes/` directory if it does not exist):

           ```html title="_includes/rybbit-analytics.html"
           {% if jekyll.environment == "production" and site.rybbit_site_id %}
             <script src="{{ site.rybbit_instance_url | default: 'https://app.rybbit.io' }}/api/script.js?siteId={{ site.rybbit_site_id }}" defer></script>
           {% endif %}
           ```

           The `jekyll.environment` check keeps the script out of local `jekyll serve` builds; the `site.rybbit_site_id` check keeps it out of builds with no ID configured.

        3. Include it from your layout's `<head>`:

           ```html title="_layouts/default.html"
           <head>
             ...
             {% include rybbit-analytics.html %}
           </head>
           ```
      </Tab>

      <Tab value="Layout file">
        Open `_layouts/default.html` and paste the snippet inside `<head>`, wrapped in a production check so local `jekyll serve` builds are not tracked:

        ```html title="_layouts/default.html"
        <head>
          ...
          {% if jekyll.environment == "production" %}
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>
    </Tabs>

    Build for production and deploy the generated `_site/` directory:

    ```bash
    JEKYLL_ENV=production jekyll build
    ```

    GitHub Pages sets `jekyll.environment` to `production` during its own build, so no extra configuration is needed there.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `jekyll serve` and a plain `jekyll build` run with `jekyll.environment` set to `development`, so the production guard removes the tag. Build with `JEKYLL_ENV=production` and check that output.
* **Config changes not applied**: Jekyll reads `_config.yml` once at startup, so restart `jekyll serve` after adding `rybbit_site_id`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Joomla (/fr/docs/guides/joomla)





Joomla has no built-in head-code setting, so the snippet goes in either a **Custom** module assigned to every page or in your template's `index.php`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Joomla [#add-the-snippet-to-joomla]

    <Tabs items="[&#x22;Custom module&#x22;, &#x22;Template file&#x22;]">
      <Tab>
        No file edits are needed, and the module survives template updates.

        1. In the Administrator panel go to **Content → Site Modules** (**Extensions → Modules** on Joomla 3), click **New** and choose **Custom**.

        2. Set **Title** to `Rybbit`, **Show Title** to **Hide**, and **Position** to any position your template renders on every page. Templates rarely expose a `<head>` position; the loader below moves the script into the head from wherever the module is rendered.

        3. In the editor, use the **Toggle Editor** button (or **Code** view) so the script is not stripped, then paste:

           ```html
           <script>
           (function () {
             var s = document.createElement("script");
             s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
             s.defer = true;
             document.head.appendChild(s);
           })();
           </script>
           ```

        4. Set **Status** to **Published**, choose **On all pages** under **Menu Assignment**, and click **Save & Close**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Edit a child template (Joomla 4.1+) or your own copy of the template, otherwise the change is lost on the next template update.
        </Callout>

        1. Go to **System → Site Templates** and open your active template.

        2. Open `index.php` and add the snippet just before `</head>`:

           ```php
           <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
           </head>
           ```

        3. Click **Save & Close**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Module not on the page**: confirm it is published, assigned to **On all pages**, and that the chosen position exists in your template. Then clear the cache under **System → Clear Cache**.
* **TinyMCE strips the script**: open the **Editor - TinyMCE** plugin under **System → Plugins** (**Extensions → Plugins** on Joomla 3) and add `script[src|defer]` to **Extended Valid Elements**, or keep using the toggled-off editor when saving the module.
* **Page caching**: the **System - Page Cache** plugin serves cached HTML, so clear the cache after adding the snippet. The script itself loads client-side and works with cached pages.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Kajabi (/fr/docs/guides/kajabi)





Kajabi has a site-wide **Header Page Scripts** field under **Site details** that puts code in the `<head>` of every page, but it deliberately skips Offer checkout and upsell pages. Those have their own **Checkout Tracking Code** setting, so a full install is two pastes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Kajabi [#add-the-snippet-to-kajabi]

    **Site-wide pages**

    1. From the **Dashboard**, open **Settings**.
    2. Under **Site settings**, click **Site details**.
    3. Scroll to **Page scripts** and paste the snippet into **Header Page Scripts**.
    4. Save.

    **Checkout and upsell pages**

    1. From the **Dashboard**, open **Settings**.
    2. Under **Payment settings**, click **Checkout**.
    3. In the **Checkout Tracking Code** section, click to edit the **Header tracking code** and paste the same snippet.
    4. Save.

    <Callout type="info">
      Do not paste the snippet into a page's **Custom Code** section (under **Customize > Settings**). That field is for CSS and JavaScript without `<style>` or `<script>` tags, and it only applies to that one page.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Checkout pages missing from the dashboard**: Header Page Scripts do not run on Offer checkout or upsell pages. Add the snippet under **Settings > Checkout > Checkout Tracking Code** as well.
* **Both fields filled, one visitor, two sites?** Use the same site ID in both places so a visitor who browses your site and then buys is one session, and funnels can follow them through checkout.
* **Snippet added to a page's Custom Code block instead**: the **Add block > Custom Code** block does accept `<script>` tags, but it only covers that page. Keep the site-wide field as the source of truth.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Kirby (/fr/docs/guides/kirby)





Kirby templates are plain PHP files in `site/templates/`, and shared markup lives in `site/snippets/`. The snippet goes into whichever file owns your `<head>`: the Starterkit's `site/snippets/header.php`, or the template itself in a Plainkit project.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Kirby [#add-the-snippet-to-kirby]

    <Tabs items="[&#x22;Starterkit&#x22;, &#x22;Plainkit&#x22;]">
      <Tab>
        The Starterkit renders the document head from a shared snippet that every template includes with `<?php snippet('header') ?>`.

        1. Open `site/snippets/header.php`.
        2. Add the tag before `</head>`:

        ```php title="site/snippets/header.php"
        <head>
          <meta charset="utf-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title><?= $site->title() ?> | <?= $page->title() ?></title>
          <?= css(['assets/css/index.css', '@auto']) ?>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        3. Save. Every template that calls `snippet('header')` now loads the script.
      </Tab>

      <Tab>
        The Plainkit's `site/templates/default.php` contains only `<h1><?= $page->title() ?></h1>` and no document structure, so add the tag wherever you build your `<head>`. The usual pattern is a header snippet included by each template:

        ```php title="site/snippets/header.php"
        <!DOCTYPE html>
        <html lang="en">
        <head>
          <meta charset="utf-8">
          <title><?= $page->title() ?></title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        <body>
        ```

        ```php title="site/templates/default.php"
        <?php snippet('header') ?>
        <h1><?= $page->title() ?></h1>
        <?php snippet('footer') ?>
        ```
      </Tab>
    </Tabs>

    To keep the site ID out of the snippet, add it to `site/config/config.php` and read it with `<?= option('rybbit.siteId') ?>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Page cache**: if `cache.pages.active` is enabled in `site/config/config.php`, flush `site/cache/` after editing the snippet or cached pages keep the old head.
* **Multiple header snippets**: templates that include a different header (for example `snippet('header-landing')`) need the tag added there too.
* **Panel is not tracked**: `/panel` is a separate app that does not render your templates, so editing time never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Laravel (/fr/docs/guides/laravel)





Laravel renders pages through Blade layouts, so the snippet goes into the layout file that wraps your site. Read the site ID from `config/services.php` and `.env` so it stays out of the template and differs per environment.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Laravel [#add-the-snippet-to-laravel]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to `.env`:

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then register them in `config/services.php`:

    ```php filename="config/services.php"
    <?php

    return [
        // ... other services

        'rybbit' => [
            'instance_url' => env('RYBBIT_INSTANCE_URL', 'https://app.rybbit.io'),
            'site_id' => env('RYBBIT_SITE_ID'),
        ],
    ];
    ```

    Run `php artisan config:clear` if your configuration is cached, otherwise the new keys are not picked up.

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open the Blade layout that wraps your pages. In a default install this is `resources/views/layouts/app.blade.php`; Breeze and Jetstream also ship `resources/views/layouts/guest.blade.php`, and Inertia apps use `resources/views/app.blade.php`. Add the tag inside `<head>`:

    ```php filename="resources/views/layouts/app.blade.php"
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>{{ config('app.name', 'Laravel') }}</title>
        @vite(['resources/css/app.css', 'resources/js/app.js'])

        @production
            <script src="{{ config('services.rybbit.instance_url') }}/api/script.js?siteId={{ config('services.rybbit.site_id') }}" defer></script>
        @endproduction
    </head>
    ```

    `@production` only renders the tag when `APP_ENV=production`, so local development is not tracked. Drop the directive if you also want data from staging.

    If you have several layouts (for example `app` and `guest`), add the tag to each one, or move it into a partial such as `resources/views/partials/rybbit.blade.php` and `@include` it from every layout.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in production**: run `php artisan config:clear` and `php artisan view:clear` after changing `.env` or `config/services.php`; cached config and compiled views keep the old values.
* **Tag missing locally**: `@production` hides it unless `APP_ENV=production`. Set that temporarily to test, or remove the directive.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Leadpages (/fr/docs/guides/leadpages)





Every Leadpages page, site and pop-up has an **Analytics** tab in its builder settings with a **Head Section Tracking Code** field, and that is where the snippet goes. In the site builder the setting is site-wide, so one paste covers every page of the site; landing pages built on their own are tracked one page at a time.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Leadpages [#add-the-snippet-to-leadpages]

    1. Open the site or landing page in the builder.
    2. Click the **Settings** gear in the left-hand sidebar, then the **Analytics** tab.
    3. Paste the snippet into **Head Section Tracking Code**.
    4. Click **Save**, then **Update** to push the change to the published page.

    Repeat for each standalone landing page you want tracked. For sites, the code applies to every page in the site.

    Pop-ups have the same tracking code fields in their settings, but a pop-up shown on a page that already carries the snippet does not need its own copy.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: the page was saved but not updated. Click **Update** in the builder to republish.
* **Standalone pages missing**: tracking code on a site does not extend to landing pages published outside that site. Add the snippet to each one.
* **GA4 Measurement ID field**: the Analytics tab also has a field for a Google Analytics ID. That field is for GA4 only; the Rybbit snippet belongs in Head Section Tracking Code.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Lovable (/fr/docs/guides/lovable)





Lovable has no project setting for custom head code, so the snippet goes into the app's HTML head like any other code change: ask Lovable to add it in chat, or open the **Code** tab and edit the file yourself. Either way, the live app only picks it up after you publish the change.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Lovable [#add-the-snippet-to-lovable]

    <Tabs items="[&#x22;Ask Lovable&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of the app on every page. Do not remove any existing head tags.
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Check the diff Lovable shows: the tag belongs in the document head, not in a React component.
      </Tab>

      <Tab>
        Open the **Code** tab in the project toolbar (editing needs a paid plan; on the Free plan the editor is read-only). Which file holds the head depends on when the project was created:

        * **Projects created from May 13, 2026** use TanStack Start. Add the script to the `head()` of the root route in `src/routes/__root.tsx`; the `<HeadContent />` component already in that file renders it into the `<head>`:

        ```tsx title="src/routes/__root.tsx"
        export const Route = createRootRoute({
          head: () => ({
            scripts: [
              { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: true },
            ],
          }),
          component: RootComponent,
        });
        ```

        * **Older React + Vite projects** have a single `index.html` at the project root. Paste the snippet before `</head>`:

        ```html title="index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Save with **Cmd+S** / **Ctrl+S**.
      </Tab>
    </Tabs>

    Then click **Publish** in the top right and choose **Publish changes**. Client-side route changes inside the app are tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live app still has no script**: Lovable does not push edits to the published app automatically. A dot on the **Publish** button means unpublished changes; open it and click **Publish changes**.
* **Free plan**: the Code tab is read-only, so use the chat prompt instead.
* **Script disappeared after a later prompt**: Lovable can rewrite the head when it regenerates the layout or upgrades the template. Add "keep the Rybbit script tag" to the project's Knowledge so future edits preserve it, and re-check the page source after big changes.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Magento (/fr/docs/guides/magento)





Magento Open Source and Adobe Commerce have a **Scripts and Style Sheets** field in the design configuration that prints HTML into the `<head>` of every storefront page, so no theme edits are needed. On 2.4.7 and later the checkout page runs under a strict Content Security Policy, so the tracker's host also needs a CSP whitelist entry before it loads there.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Magento [#add-the-snippet-to-magento]

    1. In the Admin sidebar, go to **Content > Design > Configuration**.
    2. Find the row for the scope you want to track (usually the store view) and click **Edit** in the **Action** column.
    3. Expand **HTML Head**.
    4. Paste the snippet at the end of **Scripts and Style Sheets** and click **Save Configuration**.
    5. Go to **System > Cache Management** and refresh the invalidated cache types, then purge Varnish or your CDN if you use one.

    #### Allow the tracker under CSP (2.4.7 and later) [#allow-the-tracker-under-csp-247-and-later]

    Magento 2.4.7 switched the checkout page (`checkout_index_index`) to CSP restrict mode; other storefront pages stay in report-only mode. Scripts from hosts that are not whitelisted are blocked on checkout, so add the tracker's host to `script-src` and `connect-src` with a `csp_whitelist.xml` in a module of your own (plus the usual `registration.php` and `etc/module.xml`):

    ```xml title="app/code/Vendor/Rybbit/etc/csp_whitelist.xml"
    <?xml version="1.0"?>
    <csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
        <policies>
            <policy id="script-src">
                <values>
                    <value id="rybbit" type="host">https://app.rybbit.io</value>
                </values>
            </policy>
            <policy id="connect-src">
                <values>
                    <value id="rybbit" type="host">https://app.rybbit.io</value>
                </values>
            </policy>
        </policies>
    </csp_whitelist>
    ```

    Run `bin/magento setup:upgrade` and flush the cache after adding the module. If you self-host Rybbit, whitelist your own instance's domain instead.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

The order success page renders `Magento_Checkout::success.phtml` through the `checkout.success` block, which reserves an `order.success.additional.info` container for extra content. Add a block to that container from the same module as the CSP whitelist; the block reads the order from the checkout session.

```php title="app/code/Vendor/Rybbit/Block/Purchase.php"
<?php
namespace Vendor\Rybbit\Block;

class Purchase extends \Magento\Checkout\Block\Onepage\Success
{
    public function getOrder(): \Magento\Sales\Model\Order
    {
        return $this->_checkoutSession->getLastRealOrder();
    }
}
```

```xml title="app/code/Vendor/Rybbit/view/frontend/layout/checkout_onepage_success.xml"
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="order.success.additional.info">
            <block class="Vendor\Rybbit\Block\Purchase" name="rybbit.purchase" template="Vendor_Rybbit::purchase.phtml" cacheable="false"/>
        </referenceContainer>
    </body>
</page>
```

```php title="app/code/Vendor/Rybbit/view/frontend/templates/purchase.phtml"
<?php
/** @var \Vendor\Rybbit\Block\Purchase $block */
$order = $block->getOrder();
if (!$order->getId()) {
    return;
}
$items = [];
foreach ($order->getAllVisibleItems() as $item) {
    $items[] = [
        'item_id'   => $item->getSku(),
        'item_name' => $item->getName(),
        'price'     => (float) $item->getPrice(),
        'quantity'  => (int) $item->getQtyOrdered(),
    ];
}
$purchase = [
    'transaction_id' => $order->getIncrementId(),
    'value'          => (float) $order->getGrandTotal(),
    'currency'       => $order->getOrderCurrencyCode(),
    'items'          => $items,
];
?>
<script>
document.addEventListener('DOMContentLoaded', function () {
    window.rybbit.event('purchase', <?= /* @noEscape */ json_encode($purchase) ?>);
});
</script>
```

The script waits for `DOMContentLoaded` because the tracker loads with `defer`. Event properties are limited to 2048 characters of JSON, so drop `items` for stores with large orders. `getTaxAmount()` and `getShippingAmount()` are available on the same order object if you want those too.

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: design configuration is scoped, and a store-view row overrides the website and global rows. Edit the row that applies to the storefront you are checking, then flush the page cache and Varnish.
* **Tracked everywhere except checkout**: CSP restrict mode on `checkout_index_index` is blocking the script. Confirm the whitelist module is enabled and look for `Content-Security-Policy` errors naming `app.rybbit.io` in the browser console.
* **Purchase event missing**: `getLastRealOrder()` is only set in the session that placed the order, so reopening the success page later renders nothing.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Mintlify (/fr/docs/guides/mintlify)





Mintlify includes every `.js` file in your docs content directory on every page, so the snippet goes into a small JavaScript file that injects the tag.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Mintlify [#add-the-snippet-to-mintlify]

    Create a JavaScript file in your content directory, next to `docs.json` and your `.mdx` pages:

    ```javascript filename="rybbit.js"
    (function () {
      var el = document.createElement("script");
      el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
      el.defer = true;
      document.head.appendChild(el);
    })();
    ```

    Commit and deploy. Mintlify picks the file up automatically; there is nothing to register in `docs.json`. See Mintlify's [custom scripts](https://www.mintlify.com/docs/customize/custom-scripts) page for the current rules on file placement.

    To pass [script attributes](/docs/script#script-attributes) such as skip patterns, set them on the element before appending it:

    ```javascript filename="rybbit.js"
    el.setAttribute("data-skip-patterns", JSON.stringify(["/internal/**"]));
    ```

    <Callout type="info">
      Mintlify sites are single-page apps. Rybbit records client-side navigation as pageviews, so no extra code is needed.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Mintlify pages are MDX, so you can attach handlers inline:

```mdx
<button
  onClick={() => window.rybbit?.event("download_clicked", { file: "getting-started.pdf" })}
>
  Download guide
</button>
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# MkDocs (/fr/docs/guides/mkdocs)





MkDocs has an `extra_javascript` setting in `mkdocs.yml` that adds a script tag to every page, which works with any theme. If you run Material for MkDocs you can instead extend the theme and place the tag in `<head>` yourself.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to MkDocs [#add-the-snippet-to-mkdocs]

    <Tabs items="[&#x22;mkdocs.yml&#x22;, &#x22;Material theme override&#x22;]">
      <Tab value="mkdocs.yml">
        Add the script URL to `extra_javascript`. MkDocs 1.5 and later accept the mapping form with a `defer` key:

        ```yaml title="mkdocs.yml"
        extra_javascript:
          - path: https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
            defer: true
        ```

        On MkDocs 1.4 or older, list the plain URL instead:

        ```yaml title="mkdocs.yml"
        extra_javascript:
          - https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
        ```

        Themes render `extra_javascript` entries at the end of `<body>` rather than in `<head>`; the script still loads on every page.
      </Tab>

      <Tab value="Material theme override">
        1. Point Material at an overrides directory in `mkdocs.yml`:

           ```yaml title="mkdocs.yml"
           theme:
             name: material
             custom_dir: overrides
           ```

        2. Create `overrides/main.html` and fill the `extrahead` block, which Material reserves for custom tags inside `<head>`:

           ```html title="overrides/main.html"
           {% extends "base.html" %}

           {% block extrahead %}
             <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
           {% endblock %}
           ```
      </Tab>
    </Tabs>

    Rebuild with `mkdocs build` and deploy the `site/` directory (or `mkdocs gh-deploy`).

    If Material's `navigation.instant` feature is on, page changes go through the History API and Rybbit records them as pageviews without extra code.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Config error on `defer`**: the `path` / `defer` mapping needs MkDocs 1.5+. Run `mkdocs --version` and either upgrade or use the plain URL form.
* **`main.html` has no effect**: the override only applies when `theme.custom_dir` is set and the file sits at `overrides/main.html`, relative to `mkdocs.yml`.
* **Local previews are tracked**: `mkdocs serve` renders the same config as `mkdocs build`. Use a second Rybbit site for local work if that matters.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Moodle (/fr/docs/guides/moodle)





Moodle has an **Additional HTML** admin setting that adds code to every page without touching the theme. Its **Within HEAD** field is where the snippet goes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Moodle [#add-the-snippet-to-moodle]

    1. Log in as an administrator and go to **Site administration → Appearance → Additional HTML**.
    2. Paste the snippet into **Within HEAD**.
    3. Click **Save changes**.

    The snippet now loads on every page, including course pages, activities and the login page. Users must be able to reach `app.rybbit.io` from their browser; nothing is proxied through the Moodle server.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Moodle renders standard HTML, so `data-rybbit-event` attributes work anywhere you control markup, for example in a course page's HTML block or a label:

```html
<a href="/course/view.php?id=42" data-rybbit-event="course_open" data-rybbit-prop-course="42">
  Open course
</a>
```

For enrolment or completion events, call `window.rybbit.event()` from a small block of JavaScript placed in the **When BODY is closed** field of the same Additional HTML page.

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the page source**: Moodle caches rendered output. Go to **Site administration → Development → Purge caches** and reload.
* **Pages inside the mobile app are not tracked**: the Moodle app renders course content in its own WebView with its own pages; the Additional HTML setting only affects the web site.
* **Snippet pasted into Custom CSS**: theme settings such as Boost's **Raw SCSS** only accept styles. Use Additional HTML for script tags.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Nextra (/fr/docs/guides/nextra)





Nextra is a Next.js docs framework, so the snippet goes where it goes in any Next.js app: the root layout, rendered with `next/script`. Nextra 4 uses the App Router and `app/layout.jsx`; Nextra 3 uses the Pages Router and `pages/_app.jsx`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Nextra [#add-the-snippet-to-nextra]

    Use the `Script` component with `strategy="afterInteractive"` rather than a plain `<script>` tag; the `defer` attribute from the snippet is not needed.

    <Tabs items="[&#x22;Nextra 4 (App Router)&#x22;, &#x22;Nextra 3 (Pages Router)&#x22;]">
      <Tab value="Nextra 4 (App Router)">
        Add the `Script` next to the `Layout` in `app/layout.jsx` (or `.tsx`):

        ```jsx title="app/layout.jsx"
        import { Footer, Layout, Navbar } from "nextra-theme-docs";
        import { Head } from "nextra/components";
        import { getPageMap } from "nextra/page-map";
        import Script from "next/script";
        import "nextra-theme-docs/style.css";

        export default async function RootLayout({ children }) {
          return (
            <html lang="en" dir="ltr" suppressHydrationWarning>
              <Head />
              <body>
                <Layout
                  navbar={<Navbar logo={<b>My Docs</b>} />}
                  pageMap={await getPageMap()}
                  footer={<Footer>MIT {new Date().getFullYear()} © My Docs.</Footer>}
                >
                  {children}
                </Layout>
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```
      </Tab>

      <Tab value="Nextra 3 (Pages Router)">
        Create `pages/_app.jsx` if your project does not have one, and render the `Script` beside the page:

        ```jsx title="pages/_app.jsx"
        import Script from "next/script";

        export default function App({ Component, pageProps }) {
          return (
            <>
              <Component {...pageProps} />
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </>
          );
        }
        ```

        Do not put the tag in the `head` option of `theme.config.jsx`: that option renders through `next/head`, and Next.js warns against loading scripts there.
      </Tab>
    </Tabs>

    Nextra navigates between pages client-side. Rybbit records those route changes as pageviews, so no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Only the docs pages are tracked**: in Nextra 4 the tag belongs in the root `app/layout.jsx`, not in a nested `app/docs/layout.jsx`, otherwise landing pages outside `docs/` are missed.
* **Upgrading from Nextra 3**: Nextra 4 dropped the Pages Router and `theme.config`. Move the `Script` from `pages/_app.jsx` to `app/layout.jsx` as part of the migration.
* **Proxying through your own domain**: see the [Next.js guide](/docs/guides/react/next-js) for rewrites; every endpoint must be rewritten, not just `script.js`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Odoo (/fr/docs/guides/odoo)





The Odoo Website app has a **Code Injection** setting in the website editor's theme panel with separate `<head>` and `</body>` fields that apply to every page of the website. The snippet goes in the `<head>` field. This works on Odoo Online, Odoo.sh and on-premise installs of Odoo 17 and 18.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Odoo [#add-the-snippet-to-odoo]

    1. Open your website's frontend and click **Edit** in the top bar.
    2. Switch to the **Theme** tab of the editor panel.
    3. Scroll to the **Advanced** section and, next to **Code Injection*&#x2A;, click &#x2A;*`<head>`**.
    4. Paste the snippet into the editor that opens and click **Save**.
    5. Click **Save** in the website editor to publish the change.

    The code is stored per website. If you run several websites from one Odoo database, switch website in the top bar and repeat the steps for each one.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Odoo eCommerce pages render standard HTML, so use `data-rybbit-event` attributes on any element you add in the editor, or call `window.rybbit.event()` from the `</body>` Code Injection field:

```html
<script>
  document.addEventListener("click", function (e) {
    if (e.target.closest("#add_to_cart")) {
      window.rybbit.event("add_to_cart");
    }
  });
</script>
```

The confirmation page is served at `/shop/confirmation`; a script that checks `window.location.pathname` there can send a `purchase` event once per order.

## Troubleshooting [#troubleshooting]

* **The `<head>` button is missing**: Code Injection requires the **Website → Editor and Designer** access right. An administrator can grant it under **Settings → Users & Companies → Users**, on the user's **Access Rights** tab.
* **Change is visible while logged in but not for visitors**: click **Save** in the editor after closing the code window; the code is published with the page.
* **Multiple websites**: the field applies only to the website currently selected in the editor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Payload (/fr/docs/guides/payload)





Payload is a headless CMS that installs into a Next.js app: the admin panel lives in the `(payload)` route group and your site in the `(frontend)` route group. The tracking snippet goes into the frontend root layout, not into Payload's config or admin panel.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Payload [#add-the-snippet-to-payload]

    <Callout type="info">
      Payload has no template or head setting to paste into. Add the snippet to the root layout of the Next.js frontend that renders your site.
    </Callout>

    In both the `website` and `blank` templates created by `npx create-payload-app`, the frontend root layout is `src/app/(frontend)/layout.tsx`. Render `next/script` there, exactly as in the [Next.js guide](/docs/guides/react/next-js), so the script loads on every public route and stays out of the admin panel under `src/app/(payload)/`.

    ```tsx title="src/app/(frontend)/layout.tsx"
    import Script from "next/script";

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            {children}
            <Script
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    The script tracks client-side route changes automatically, so Next.js `<Link>` navigation between Payload pages and posts is counted without extra code.

    If your frontend is a separate app (Nuxt, Astro, SvelteKit) that fetches from Payload's REST or GraphQL API, follow that framework's guide instead: [Nuxt](/docs/guides/vue/nuxt), [Astro](/docs/guides/astro), [SvelteKit](/docs/guides/svelte/sveltekit), [Remix](/docs/guides/react/remix).
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live Preview counts as visits**: the admin panel's Live Preview loads your frontend in an iframe at the URL set in `admin.livePreview.url`. Editors' preview sessions are tracked like any other visitor. Point `livePreview.url` at a separate preview deployment registered as its own site in Rybbit, or skip the tag in preview builds.
* **Draft preview routes**: if you use the `website` template's `/next/preview` route or Next.js draft mode, those pages are also tracked. Add `data-skip-patterns='["/next/**"]'` to the script tag to exclude them.
* **Admin panel is not tracked**: `/admin` is rendered by the `(payload)` route group, which has its own layout without the snippet. Put the tag in the `(frontend)` layout only.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Phoenix (/fr/docs/guides/phoenix)





Phoenix renders every page inside the root layout, `lib/my_app_web/components/layouts/root.html.heex`, which owns the `<html>` and `<head>` tags, so the snippet goes there. Read the site ID from application config set in `config/runtime.exs`, so it comes from an environment variable at boot and stays out of the template.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Phoenix [#add-the-snippet-to-phoenix]

    #### Configure the site ID [#configure-the-site-id]

    `config/runtime.exs` runs when the app boots, including inside a release, so it is the right place to read environment variables. Add a `:rybbit` key for your app (replace `:my_app` with your OTP app name):

    ```elixir filename="config/runtime.exs"
    config :my_app, :rybbit,
      instance_url: System.get_env("RYBBIT_INSTANCE_URL", "https://app.rybbit.io"),
      site_id: System.get_env("RYBBIT_SITE_ID")
    ```

    Then set the variables where the app runs:

    ```bash
    export RYBBIT_INSTANCE_URL=https://app.rybbit.io
    export RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    #### Expose the config to the layout [#expose-the-config-to-the-layout]

    Templates in `lib/my_app_web/components/layouts/` are embedded into the `MyAppWeb.Layouts` module, so a function defined there is callable from `root.html.heex`. Add one that returns the config:

    ```elixir filename="lib/my_app_web/components/layouts.ex"
    defmodule MyAppWeb.Layouts do
      use MyAppWeb, :html

      embed_templates "layouts/*"

      def rybbit_config, do: Application.get_env(:my_app, :rybbit, [])
    end
    ```

    #### Add the tag to the root layout [#add-the-tag-to-the-root-layout]

    Open `lib/my_app_web/components/layouts/root.html.heex` and add the tag inside `<head>`, after the existing `app.css` and `app.js` tags:

    ```html filename="lib/my_app_web/components/layouts/root.html.heex"
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta name="csrf-token" content={get_csrf_token()} />
      <.live_title suffix=" · Phoenix Framework">{assigns[:page_title] || "MyApp"}</.live_title>
      <link phx-track-static rel="stylesheet" href={~p"/assets/app.css"} />
      <script defer phx-track-static type="text/javascript" src={~p"/assets/app.js"}></script>

      <script
        :if={rybbit_config()[:site_id]}
        src={"#{rybbit_config()[:instance_url]}/api/script.js?siteId=#{rybbit_config()[:site_id]}"}
        defer
      ></script>
    </head>
    ```

    The `:if` attribute skips the tag when `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.

    #### LiveView navigation [#liveview-navigation]

    `<.link navigate>`, `<.link patch>`, `push_navigate/2` and `push_patch/2` change the URL with `history.pushState` (or `replaceState` when `replace: true`) and keep the root layout, including its `<head>`, in place. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each live navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `phx:` event listener is needed. A regular `<.link href>` does a full page load, which the script also tracks.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `config/runtime.exs` is evaluated at boot, so restart the app or release after changing `RYBBIT_SITE_ID`. Check with `Application.get_env(:my_app, :rybbit)` in `iex -S mix`.
* **Content Security Policy**: if you set a `content-security-policy` header in a plug, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Podia (/fr/docs/guides/podia)





Podia has a **Third-party code** setting under **Settings > Analytics** that adds the snippet to every public page of your site, including checkout. Podia inserts custom code just before the closing `</body>` tag rather than in `<head>`; the Rybbit script loads with `defer` and works the same from either position.

<Callout type="warn">
  Third-party code is available on Podia's **Mover** and **Shaker** plans. On the free plan the Third-party code option is not shown.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Podia [#add-the-snippet-to-podia]

    1. From your home feed, click your site name and choose **Admin**.
    2. In the Admin sidebar, open **Settings > Analytics**.
    3. Click **Edit** next to **Third-party code**.
    4. Paste the snippet into the **Website tracking code** field.
    5. Click **Save**. The code is live as soon as it is saved; there is no separate publish step.

    The website tracking code runs on every public page of your site and on checkout pages. It does not run inside logged-in areas such as the customer dashboard, product viewer or community spaces.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Podia has a second field, **Conversion tracking code**, directly below the website tracking code. Code in that field runs only on the thank-you page after a purchase or membership signup, and Podia exposes the order as a `Podia.Conversion` object on that page (once per order; it is gone after a refresh).

Paste this into **Conversion tracking code** to send a `purchase` event with the order details:

```html
<script>
(function () {
  var c = window.Podia && window.Podia.Conversion;
  if (!c) return;
  var payload = {
    product: c.object.name,
    order_id: c.object.order_id,
    value: c.revenue,
    currency: c.currency
  };
  var start = Date.now();
  (function send() {
    if (window.rybbit && typeof window.rybbit.event === "function") {
      return window.rybbit.event("purchase", payload);
    }
    if (Date.now() - start < 8000) setTimeout(send, 150);
  })();
})();
</script>
```

The short polling loop is there because Podia runs the conversion code before the deferred tracking script has finished loading. `revenue` is `0` for free products and free membership plans, so filter on `value` in the dashboard if you only want paid orders.

## Troubleshooting [#troubleshooting]

* **No Third-party code option**: the site is on the free plan. Third-party code requires Mover or Shaker.
* **No pageviews while you test**: Podia does not output tracking code when you are logged in to your own Podia account. Test in a private window, or log out first.
* **Logged-in member pages are missing**: expected. Custom code runs only on public pages and checkout, not in the customer dashboard, product viewer or community.
* **Duplicate purchase events**: `Podia.Conversion` is only present on the first load of the thank-you page, so a refresh does not resend. If you see duplicates, make sure the event script is in Conversion tracking code only and not also in Website tracking code.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Preact (/fr/docs/guides/preact)





A Preact app scaffolded with `npm init preact` (or Vite's `preact` template) has a single `index.html` at the project root. Paste the snippet into its `<head>` and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Preact [#add-the-snippet-to-preact]

    Open `index.html` at the root of the project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Vite + Preact</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/index.jsx"></script>
      </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Route changes made by `preact-iso`, `preact-router` or a similar router are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw.

```jsx title="src/components/SignupButton.jsx"
export function SignupButton() {
  const handleClick = () => {
    if (window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# PrestaShop (/fr/docs/guides/prestashop)





PrestaShop's back office has no built-in setting for custom `<head>` code, so the snippet goes in either through a header-injection module from the Addons marketplace or directly into your theme's `head.tpl`. Either way, clear the cache afterwards.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to PrestaShop [#add-the-snippet-to-prestashop]

    <Tabs items="[&#x22;Custom code module&#x22;, &#x22;Theme files&#x22;]">
      <Tab>
        1. In the back office, go to **Modules > Module Manager** (or **Module Catalog**) and install a module that injects custom HTML into the page header, for example a "Custom HTML" or "Header code" module from the [PrestaShop Addons marketplace](https://addons.prestashop.com/).
        2. Open the module's configuration, paste the snippet into its head / header code field, and save.
        3. Go to **Advanced Parameters > Performance** and click **Clear cache**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Edit a child theme. Changes to the parent theme are lost on theme updates.
        </Callout>

        1. Over FTP/SFTP or a file manager, open `/themes/your-theme-name/templates/_partials/head.tpl`.
        2. Paste the snippet at the end of the file, before the closing `</head>` tag, and save.
        3. Go to **Advanced Parameters > Performance** and click **Clear cache**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Add this to your theme's `order-confirmation.tpl`, or output it from a module hooked to the order confirmation page. PrestaShop renders templates with Smarty, so the `$order` variables are filled in with the order data:

```html
{if isset($order)}
<script>
(function () {
  function waitForRybbit(callback, timeout) {
    var start = Date.now();
    (function check() {
      if (window.rybbit && typeof window.rybbit.event === 'function') {
        callback();
      } else if (Date.now() - start < timeout) {
        setTimeout(check, 100);
      }
    })();
  }

  waitForRybbit(function () {
    window.rybbit.event('purchase', {
      transaction_id: '{$order.details.reference}',
      value: {$order.totals.total.amount},
      currency: '{$order.totals.total.currency}'
    });
  }, 5000);
})();
</script>
{/if}
```

`waitForRybbit` polls until the tracking script from `head.tpl` has defined `window.rybbit`, so the event is not lost when the confirmation script runs first.

## Troubleshooting [#troubleshooting]

* **Script not on the page**: clear the cache under **Advanced Parameters > Performance**, and temporarily disable any JavaScript optimisation or combine/minify module.
* **Theme updates overwrite the snippet**: keep template edits in a child theme; parent-theme changes are lost on update.
* **Purchase event missing**: the `$order` Smarty variables differ between PrestaShop versions. Compare them with your version's `order-confirmation.tpl` and place a test order to confirm the event arrives.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Qwik (/fr/docs/guides/qwik)





A Qwik City app renders the whole document from `src/root.tsx`, which owns the `<head>` and `<body>` elements. Add the snippet to that `<head>` and it is on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Qwik [#add-the-snippet-to-qwik]

    Open `src/root.tsx` and add the tag inside `<head>`, after `<RouterHead />`:

    ```tsx title="src/root.tsx"
    import { component$ } from "@builder.io/qwik";
    import { QwikCityProvider, RouterOutlet } from "@builder.io/qwik-city";
    import { RouterHead } from "./components/router-head/router-head";

    import "./global.css";

    export default component$(() => {
      return (
        <QwikCityProvider>
          <head>
            <meta charset="utf-8" />
            <RouterHead />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body lang="en">
            <RouterOutlet />
          </body>
        </QwikCityProvider>
      );
    });
    ```

    `src/components/router-head/router-head.tsx` renders per-route `head` exports (title, meta, links). Keep the Rybbit tag in `root.tsx` so it does not depend on any route's `head` export.

    Navigations through Qwik City's `<Link>` component are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a `$` event handler. Handlers only run in the browser, so `window` is always defined; guard against a blocked or still-loading script.

```tsx title="src/components/signup-button.tsx"
import { component$ } from "@builder.io/qwik";

export const SignupButton = component$(() => {
  return (
    <button
      onClick$={() => {
        if (window.rybbit) {
          window.rybbit.event("signup_click", { location: "hero" });
        }
      }}
    >
      Sign up
    </button>
  );
});
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ruby on Rails (/fr/docs/guides/rails)





Rails wraps every page in `app/views/layouts/application.html.erb`, so the snippet goes into that layout's `<head>`. Read the site ID from a custom `config.x` setting fed by an environment variable, so the template stays free of hard-coded IDs and each environment can use its own site.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ruby on Rails [#add-the-snippet-to-ruby-on-rails]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to your environment (`.env` if you use dotenv-rails, otherwise your host's environment settings):

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then expose them through the `config.x` namespace in `config/application.rb`:

    ```ruby filename="config/application.rb"
    module MyApp
      class Application < Rails::Application
        # ... existing configuration

        config.x.rybbit.instance_url = ENV.fetch("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
        config.x.rybbit.site_id = ENV["RYBBIT_SITE_ID"]
      end
    end
    ```

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open `app/views/layouts/application.html.erb` and add the tag inside `<head>`, after the stylesheet and JavaScript tags:

    ```erb filename="app/views/layouts/application.html.erb"
    <head>
      <title><%= content_for(:title) || "MyApp" %></title>
      <meta name="viewport" content="width=device-width,initial-scale=1">
      <%= csrf_meta_tags %>
      <%= csp_meta_tag %>
      <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
      <%= javascript_importmap_tags %>

      <% if Rails.configuration.x.rybbit.site_id.present? %>
        <script src="<%= Rails.configuration.x.rybbit.instance_url %>/api/script.js?siteId=<%= Rails.configuration.x.rybbit.site_id %>" defer></script>
      <% end %>
    </head>
    ```

    The `if` guard skips the tag wherever `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.

    If you have more than one HTML layout (for example `application.html.erb` and `admin.html.erb`), add the tag to each, or move it into a partial such as `app/views/layouts/_rybbit.html.erb` and `<%= render "layouts/rybbit" %>` from every layout. Mailer layouts do not need it.

    #### Turbo and Hotwire [#turbo-and-hotwire]

    Turbo Drive replaces the page `<body>` on each visit, merges the `<head>`, and pushes the new URL with `history.pushState`. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so every Turbo visit is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `turbo:load` listener is needed. Because the script tag is in `<head>` and identical on every page, Turbo Drive keeps the existing tag instead of loading it again.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `config/application.rb` is read once at boot, so restart the server after changing `RYBBIT_SITE_ID`. Check `Rails.configuration.x.rybbit.site_id` in `rails console` if the tag does not render.
* **Content Security Policy**: if you set a policy in `config/initializers/content_security_policy.rb`, add your Rybbit host to `script_src` and `connect_src`, or the browser blocks both the script and the `/api/track` requests. Alternatively [proxy the script](/docs/proxy-guide) through your own domain so no extra origin is needed.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Replit (/fr/docs/guides/replit)





Replit has no publishing setting for custom head code, so the snippet goes into the app's HTML entry file: ask Agent to add it, or open the file in the workspace and paste it yourself. The change reaches the live URL only after you republish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Replit [#add-the-snippet-to-replit]

    <Tabs items="[&#x22;Ask Agent&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the Agent chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of the app's HTML entry file so it loads on every page. Keep all existing head tags.
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Review the change before you approve it: the tag belongs in the HTML document, not in a React component or server file.
      </Tab>

      <Tab>
        Open the file that owns the `<head>` from the **Files** pane of the workspace:

        * Agent-built web apps are typically a Vite + React client with an Express server, and the HTML entry is `client/index.html`. Some projects keep it at `index.html` in the project root.
        * Next.js projects use `app/layout.tsx` with `next/script`, as in the [Next.js guide](/docs/guides/react/next-js).
        * Plain HTML projects (Static deployments): add the tag to every page, or to the shared template if you have one.

        Paste the snippet before `</head>`:

        ```html title="client/index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```
      </Tab>
    </Tabs>

    Then click **Publish** in the upper right (or **Republish** for an app that is already live) so a new release goes out at the same URL. In-app route changes are tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live app has no script**: changes in the Project Editor do not replace the live release on their own. Test in Preview, then click **Republish**.
* **Agent rewrote the file**: a later request can regenerate `client/index.html`. Tell Agent to keep the Rybbit script when you ask for layout changes, and re-check the page source after large refactors.
* **Numbers differ from Replit's deployment analytics**: Replit counts requests at the server; Rybbit counts browser pageviews after ad blockers and bot filtering, so the two rarely match exactly.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Sanity (/fr/docs/guides/sanity)





Sanity is a headless CMS: your frontend queries content from the Content Lake and Sanity Studio is only the editing app. The tracking snippet therefore goes into the frontend that renders your site, not into Sanity.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Sanity [#add-the-snippet-to-sanity]

    <Callout type="info">
      Sanity has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Sanity.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Sanity frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby)
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Embedded Studio pageviews**: if Sanity Studio is mounted inside your frontend (for example at `/studio` in a Next.js app), the snippet in your root layout also runs there. Add `data-skip-patterns='["/studio/**"]'` to the script tag so editor sessions are not counted as visits.
* **Hosted Studio is not tracked**: a Studio deployed to `*.sanity.studio` is a separate app without the snippet, so time spent editing never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Shopify Hydrogen (/fr/docs/guides/shopify-hydrogen)





Hydrogen storefronts render the HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file's `Layout` component, and the tracker's host is added to the Content Security Policy that `app/entry.server.tsx` builds. This guide is for headless Hydrogen storefronts; for an Online Store theme, see the [Shopify guide](/docs/guides/shopify).

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Shopify Hydrogen [#add-the-snippet-to-shopify-hydrogen]

    Hydrogen ships with a nonce-based CSP, so a plain `<script>` tag without the nonce is blocked. Use Hydrogen's `Script` component, which adds the nonce for you.

    1. Open `app/root.tsx` and add the tag inside `<head>` of the `Layout` component:

    ```tsx title="app/root.tsx"
    import { Analytics, getShopAnalytics, Script, useNonce } from "@shopify/hydrogen";

    export function Layout({children}: {children?: React.ReactNode}) {
      const nonce = useNonce();

      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width,initial-scale=1" />
            <Meta />
            <Links />
            <Script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer />
          </head>
          <body>
            {children}
            <ScrollRestoration nonce={nonce} />
            <Scripts nonce={nonce} />
          </body>
        </html>
      );
    }
    ```

    2. Open `app/entry.server.tsx` and allow the tracker's host in the CSP. Values you pass for `connectSrc` are merged with Hydrogen's defaults, but `scriptSrc` has no default to merge with (it falls back to `default-src`), so list Shopify's CDN alongside Rybbit:

    ```tsx title="app/entry.server.tsx"
    const {nonce, header, NonceProvider} = createContentSecurityPolicy({
      shop: {
        checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
        storeDomain: context.env.PUBLIC_STORE_DOMAIN,
      },
      scriptSrc: ["'self'", "https://cdn.shopify.com", "https://app.rybbit.io"],
      connectSrc: ["https://app.rybbit.io"],
    });
    ```

    `connect-src` lets the tracker post events; `script-src` is needed because features such as session replay load a second script from the same host at runtime. If you self-host Rybbit, use your instance's domain.

    Restart the dev server. Client-side navigation between routes is tracked automatically as pageviews. Projects created before Hydrogen moved to React Router import `Meta`, `Links` and `Scripts` from `@remix-run/react`; the edit is the same.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Hydrogen's `Analytics.Provider` already publishes storefront events (`product_viewed`, `product_added_to_cart`, `cart_updated` and others), so subscribe to them once in a small component instead of instrumenting each route.

```tsx title="app/components/RybbitAnalytics.tsx"
import { useAnalytics } from "@shopify/hydrogen";
import { useEffect } from "react";

export function RybbitAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register("Rybbit");

  useEffect(() => {
    subscribe("product_viewed", (data) => {
      const product = data.products[0];
      if (!product) return;
      window.rybbit?.event("view_item", {
        item_id: product.sku || product.variantId,
        item_name: product.title,
        item_variant: product.variantTitle,
        price: Number(product.price),
      });
    });
    subscribe("product_added_to_cart", (data) => {
      const line = data.currentLine;
      if (!line) return;
      window.rybbit?.event("add_to_cart", {
        item_id: line.merchandise.sku || line.merchandise.id,
        item_name: line.merchandise.product.title,
        price: Number(line.cost.totalAmount.amount),
        currency: line.cost.totalAmount.currencyCode,
        quantity: line.quantity,
      });
    });
    ready();
  }, []);

  return null;
}
```

Render `<RybbitAnalytics />` inside `<Analytics.Provider>` in the `App` component of `app/root.tsx`. Declare `window.rybbit` with the type from [Track events](/docs/track-events#typescript-support) so TypeScript accepts the calls. Skip `page_viewed`: the tracker records route changes itself.

<Callout type="info">
  Checkout does not run in Hydrogen. Track purchases with the custom web pixel from the [Shopify guide](/docs/guides/shopify#purchase), which works for Hydrogen and Online Store checkouts alike.
</Callout>

## Troubleshooting [#troubleshooting]

* **`Refused to load the script` in the console**: the CSP change in `entry.server.tsx` is missing or the dev server was not restarted. The nonce alone is not enough once session replay loads its second script.
* **`POST /api/track` blocked**: `connectSrc` does not include the tracker's host. Self-hosted instances need their own domain here.
* **Early events dropped**: on a cold load a subscription can fire before the deferred script runs. The optional chaining above skips those; wrap the calls in `window.rybbit.onReady()` if you need every one.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Shopify (/fr/docs/guides/shopify)





On Shopify the snippet goes into your theme's `theme.liquid` layout, which wraps every storefront page. Checkout runs on Shopify's own sandboxed pages, so purchases are tracked separately through a custom web pixel.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Shopify [#add-the-snippet-to-shopify]

    1. In Shopify admin, go to **Online Store > Themes**.
    2. On your current theme, click the &#x2A;*...** button next to **Customize** and choose **Edit code**.
    3. Open `theme.liquid` in the **Layout** folder.
    4. Paste the snippet just before the closing `</head>` tag and click **Save**.

    Theme updates can overwrite `theme.liquid`. Shopify has no child-theme system, so after updating a purchased theme, re-add the snippet.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Storefront templates can call `window.rybbit.event()` directly. Wrap the calls in a `DOMContentLoaded` listener because the tracking script is loaded with `defer`, and divide Liquid prices by 100 because they are in cents.

<Callout type="warn">
  Back up your theme before editing code. Liquid object names such as `product.selected_or_first_available_variant` and the form selectors below vary between themes, so adjust them to match yours.
</Callout>

#### View product [#view-product]

Add to your main product template (`sections/main-product.liquid` or `templates/product.liquid`, depending on the theme):

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var variant = {{ product.selected_or_first_available_variant | json }};
  window.rybbit.event('view_item', {
    item_id: variant.sku || variant.id,
    item_name: {{ product.title | json }},
    item_variant: variant.title === 'Default Title' ? null : variant.title,
    price: variant.price / 100,
    currency: {{ cart.currency.iso_code | json }}
  });
});
</script>
```

#### Add to cart [#add-to-cart]

In the same template, listen on the product form. Themes with an AJAX cart drawer usually fire their own JavaScript event after an item is added; hooking that is more reliable than the form submit.

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var form = document.querySelector('form[action="/cart/add"]');
  if (!form) return;
  form.addEventListener('submit', function () {
    var variant = {{ product.selected_or_first_available_variant | json }};
    var qty = form.querySelector('[name="quantity"]');
    window.rybbit.event('add_to_cart', {
      item_id: variant.sku || variant.id,
      item_name: {{ product.title | json }},
      price: variant.price / 100,
      currency: {{ cart.currency.iso_code | json }},
      quantity: qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1
    });
  });
});
</script>
```

#### Begin checkout [#begin-checkout]

Add to your cart template (`sections/main-cart-items.liquid` or `templates/cart.liquid`) to track clicks on the checkout button:

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var button = document.querySelector('[name="checkout"]');
  if (!button) return;
  button.addEventListener('click', function () {
    var cart = {{ cart | json }};
    window.rybbit.event('begin_checkout', {
      currency: cart.currency,
      value: cart.total_price / 100,
      items: cart.items.map(function (item) {
        return { item_id: item.sku || item.variant_id, quantity: item.quantity, price: item.final_price / 100 };
      })
    });
  });
});
</script>
```

Event properties are limited to 2048 characters of serialised JSON and larger payloads are rejected, not truncated. Keep `items` compact, or send only the totals for large carts.

#### Purchase [#purchase]

Checkout and the order status page do not load your theme, and the old **Order status page > Additional scripts** field is deprecated: view-only since August 28, 2025, with non-Plus stores required to migrate by August 26, 2026. Track purchases with a custom web pixel from [Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations) instead.

Pixels run in a sandbox with no access to `window.rybbit`, so the pixel posts the event straight to Rybbit's track endpoint.

1. In Shopify admin, go to **Settings > Customer events**.
2. Click **Add custom pixel**, name it `Rybbit`, and click **Add pixel**.
3. Paste the code below, replace `YOUR_SITE_ID`, then **Save** and **Connect** the pixel.

```javascript
analytics.subscribe("checkout_completed", (event) => {
  const checkout = event.data.checkout;
  const items = (checkout.lineItems || []).map((li) => ({
    id: li.variant?.sku || li.variant?.id,
    qty: li.quantity,
    price: li.variant?.price?.amount,
  }));

  fetch("https://app.rybbit.io/api/track", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    keepalive: true,
    body: JSON.stringify({
      type: "custom_event",
      site_id: "YOUR_SITE_ID",
      event_name: "purchase",
      // properties must be a JSON string of at most 2048 characters
      properties: JSON.stringify({
        transaction_id: checkout.order?.id || checkout.token,
        value: checkout.totalPrice?.amount,
        currency: checkout.currencyCode,
        items,
      }),
    }),
  });
});
```

`checkout_completed` fires once per placed order. The same [Customer Events](https://shopify.dev/docs/api/customer-events) API also exposes `product_added_to_cart` and `checkout_started`, so you can move add-to-cart and begin-checkout into the pixel too if theme code is unreliable on your store.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# SolidJS (/fr/docs/guides/solid)





A client-side Solid app built with Vite has a single `index.html` at the project root; a SolidStart app renders its document from `src/entry-server.tsx`. Paste the snippet into the `<head>` of whichever file your project has and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to SolidJS [#add-the-snippet-to-solidjs]

    <Tabs items="[&#x22;Vite&#x22;, &#x22;SolidStart&#x22;]">
      <Tab value="Vite">
        Open `index.html` at the root of the project (the file `npm create solid@latest` generates for the vanilla templates) and paste the snippet inside `<head>`:

        ```html title="index.html"
        <!DOCTYPE html>
        <html lang="en">
          <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <title>Solid App</title>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            <div id="root"></div>
            <script src="/src/index.tsx" type="module"></script>
          </body>
        </html>
        ```
      </Tab>

      <Tab value="SolidStart">
        SolidStart has no `index.html`. The `<html>` document is the `document` prop of `<StartServer>` in `src/entry-server.tsx`; `src/app.tsx` only renders the router inside it. Add the tag to `<head>` next to `{assets}`:

        ```tsx title="src/entry-server.tsx"
        // @refresh reload
        import { createHandler, StartServer } from "@solidjs/start/server";

        export default createHandler(() => (
          <StartServer
            document={({ assets, children, scripts }) => (
              <html lang="en">
                <head>
                  <meta charset="utf-8" />
                  <meta name="viewport" content="width=device-width, initial-scale=1" />
                  <link rel="icon" href="/favicon.ico" />
                  <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
                  {assets}
                </head>
                <body>
                  <div id="app">{children}</div>
                  {scripts}
                </body>
              </html>
            )}
          />
        ));
        ```

        Restart the dev server after the change.
      </Tab>
    </Tabs>

    Route changes made by `@solidjs/router` (including SolidStart's file routes) are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw; in SolidStart the guard also covers server rendering.

```tsx title="src/components/SignupButton.tsx"
export default function SignupButton() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Squarespace (/fr/docs/guides/squarespace)





Squarespace injects custom HTML into every page through its **Code Injection** panel, so no template edits are needed.

<Callout type="warn">
  Code Injection is available on the **Business** and **Commerce** plans. It is not available on the Personal plan.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Squarespace [#add-the-snippet-to-squarespace]

    1. From the Home Menu, open **Settings**.
    2. Open **Website**, then **Code Injection** (listed under **Advanced** or **Developer** depending on your Squarespace version).
    3. Paste the snippet into the **Header** field. The script is deferred, so it does not delay page rendering.
    4. Click **Save** at the top of the panel.

    The **Footer** field also works and loads the script on every page. Leave the **Lock Page** and **Order Confirmation Page** fields alone; they only apply to those single pages.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Code Injection is missing from Settings**: the site is on the Personal plan. Upgrade to Business or Commerce.
* **Only the checkout is tracked**: the snippet was pasted into **Order Confirmation Page** instead of **Header** or **Footer**.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Starlight (/fr/docs/guides/starlight)





Starlight, the documentation theme for Astro, has a `head` option in its integration config that adds tags to every page. The snippet goes there, in `astro.config.mjs`, so no component overrides are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Starlight [#add-the-snippet-to-starlight]

    Open `astro.config.mjs` at the root of your project and add a `script` entry to the `head` array of the `starlight()` integration:

    ```javascript title="astro.config.mjs"
    import { defineConfig } from "astro/config";
    import starlight from "@astrojs/starlight";

    export default defineConfig({
      integrations: [
        starlight({
          title: "My Docs",
          head: [
            {
              tag: "script",
              attrs: {
                src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                defer: true,
              },
            },
          ],
        }),
      ],
    });
    ```

    Each `head` entry becomes an HTML element with the given attributes; `defer: true` renders as a boolean attribute. Rebuild with `npm run build` and deploy the `dist/` directory.

    <Callout type="info">
      Entries in `head` are written to the page as-is and skip Astro's script bundling, which is what you want for a remote tracker. Only override the `Head` component if you need to import a local asset.
    </Callout>

    Starlight serves each page as a full document, so every navigation is a normal pageview and no route-change handling is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Local previews are tracked**: `head` applies to `astro dev` as well as `astro build`. Read the site ID from an environment variable that only your deploy sets (`process.env.RYBBIT_SITE_ID`) and push the entry only when it is present, or keep a separate site in Rybbit for development.
* **Tag missing after editing the config**: the dev server restarts itself when `astro.config.mjs` changes, but a deployed site needs a fresh build.
* **Head component override**: if your project already overrides Starlight's `Head` component, make sure it still renders the default head (the override docs show how), otherwise config `head` entries are dropped with it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Statamic (/fr/docs/guides/statamic)





Statamic wraps every template in a layout, and a fresh install uses `resources/views/layout.antlers.html` by default. The snippet goes in that layout's `<head>`, so it loads on every page without touching individual templates.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Statamic [#add-the-snippet-to-statamic]

    1. Open `resources/views/layout.antlers.html`.
    2. Add the tag before `</head>`:

    ```html title="resources/views/layout.antlers.html"
    <!doctype html>
    <html lang="{{ site:short_locale }}">
    <head>
        <meta charset="utf-8">
        <title>{{ title }} | {{ site:name }}</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        {{ template_content }}
    </body>
    </html>
    ```

    3. Save. Templates rendered through this layout (`{{ template_content }}`) now include the script.

    If an entry or collection sets a different `layout` field, add the tag to that layout file too, or move it into a partial such as `resources/views/partials/rybbit.antlers.html` and `{{ partial:rybbit }}` it from each layout. If your views use Blade (`layout.blade.php`), the same tag goes in the same place.

    To keep the site ID out of version control, put it in `.env` as `RYBBIT_SITE_ID` and use `{{ config:services:rybbit:site_id }}` after adding a `rybbit` entry to `config/services.php`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Static caching**: with `half` or `full` static caching enabled in `config/statamic/static_caching.php`, run `php please static:clear` after editing the layout, otherwise cached pages keep the old head.
* **Live Preview counts as visits**: the control panel's Live Preview renders your entry in an iframe at its real URL with a `token` query parameter. Editors' previews are tracked like any other visit, so check analytics from the live site rather than the control panel.
* **Control panel is not tracked**: `/cp` uses Statamic's own views, so the snippet never runs there.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Storyblok (/fr/docs/guides/storyblok)





Storyblok is a headless CMS: it stores content and delivers it through its APIs, while your frontend renders the pages. The tracking snippet therefore goes into the frontend's root layout, not into Storyblok.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Storyblok [#add-the-snippet-to-storyblok]

    <Callout type="info">
      Storyblok has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Storyblok.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Remix](/docs/guides/react/remix)
        * [Gatsby](/docs/guides/react/gatsby)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>

    The script tracks client-side route changes automatically, so navigation between stories in any of these frameworks is counted without extra code.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Visual Editor previews count as visits**: the Visual Editor loads your frontend in an iframe at the **Preview URL** set under **Settings > Visual Editor**, appending `_storyblok` and `_storyblok_tk[...]` query parameters. Editors' preview sessions are tracked like real visitors. Point the Preview URL at a separate preview deployment registered as its own site in Rybbit, or leave the tag out of builds that use the preview token.
* **Preview parameters in tracked URLs**: if the same deployment serves both the live site and the Visual Editor, the `_storyblok` parameters show up in tracked page URLs. Add `data-track-query="false"` to the script tag to drop query strings.
* **The Storyblok app is not tracked**: the snippet only runs in your frontend, so time spent in `app.storyblok.com` never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Strapi (/fr/docs/guides/strapi)





Strapi is a headless CMS: it exposes your content over a REST or GraphQL API and does not render your website. The tracking snippet therefore goes into the frontend that consumes the Strapi API, not into Strapi.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Strapi [#add-the-snippet-to-strapi]

    <Callout type="info">
      Strapi has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Strapi.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Strapi frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Nuxt is a popular Strapi frontend. Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby)
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **The admin panel is not tracked**: the Strapi admin at `/admin` is served by the Strapi server, not by your frontend, so it never loads the snippet. Content editors' activity does not appear in Rybbit, which is usually what you want.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# systeme.io (/fr/docs/guides/systeme-io)





systeme.io has an account-wide **Tracking code** setting under **Settings > Sales Funnels** that adds code to every funnel page, plus a per-page **Tracking** section with a header field in the page editor. Use the account-wide setting unless you only want to track certain pages.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to systeme.io [#add-the-snippet-to-systemeio]

    <Tabs items="[&#x22;All funnels&#x22;, &#x22;One page&#x22;]">
      <Tab>
        1. Click your **profile picture** in the top-right corner and choose **Settings**.
        2. Select **Sales Funnels** in the left menu.
        3. Paste the snippet into the **Tracking code** box and click **Save**.

        The code is added to every page in every funnel on the account.
      </Tab>

      <Tab>
        1. Open the funnel, select the page in the list on the left and click **Edit page**.
        2. Click **Settings** in the upper-left corner of the editor and scroll to the **Tracking** section.
        3. Paste the snippet into the **header** field (the one for code that belongs between `<head>` and `</head>`).
        4. Save the page.
      </Tab>
    </Tabs>

    Paste only the `<script>` tag. systeme.io asks that custom code never include `<head>`, `<body>` or `<html>` tags of its own.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Duplicate pageviews**: the snippet is in both the account-wide Tracking code and a page's Tracking section. Keep one.
* **Not visible in preview**: custom code runs on the live page only. Open the published funnel URL to test.
* **Pages outside funnels**: the Sales Funnels tracking code covers funnel pages. Blog and course pages have their own settings, so add the snippet there if you want that traffic in the same site.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Tauri (/fr/docs/guides/tauri)





Tauri v2 bundles your frontend into the app and serves it to the system webview. Install the `@rybbit/js` SDK in the frontend (or put the snippet in its `index.html`), then allow `https://app.rybbit.io` in the `app.security.csp` block of `src-tauri/tauri.conf.json`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Tauri [#add-the-snippet-to-tauri]

    <Callout type="info">
      Tauri's security guide advises against loading remote scripts such as CDN-hosted files. The SDK keeps all executable code inside the bundle, so it is the recommended method.
    </Callout>

    <Tabs items="[&#x22;@rybbit/js SDK&#x22;, &#x22;Script tag&#x22;]">
      <Tab>
        1. Install the package in your frontend project:

        ```bash
        npm install @rybbit/js
        ```

        2. Initialise it once in the frontend entry file (`src/main.ts` or equivalent):

        ```ts title="src/main.ts"
        import rybbit from "@rybbit/js";

        await rybbit.init({
          analyticsHost: "https://app.rybbit.io/api",
          siteId: "YOUR_SITE_ID",
        });
        ```

        3. Allow the analytics host in `connect-src`. Keep `ipc:` and `http://ipc.localhost`, which Tauri needs for frontend-to-Rust calls:

        ```json title="src-tauri/tauri.conf.json"
        {
          "app": {
            "security": {
              "csp": {
                "default-src": "'self'",
                "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]
              }
            }
          }
        }
        ```
      </Tab>

      <Tab>
        1. Paste the snippet into the `<head>` of your frontend's `index.html`:

        ```html title="index.html"
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        2. Allow the host in both `script-src` and `connect-src`:

        ```json title="src-tauri/tauri.conf.json"
        {
          "app": {
            "security": {
              "csp": {
                "default-src": "'self'",
                "script-src": ["'self'", "https://app.rybbit.io"],
                "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    If `app.security.csp` is unset, Tauri applies no CSP and neither change is needed. Route changes inside the app are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Works in `tauri dev` but not in the built app on macOS, Linux or iOS**: in development the frontend is served from your dev server (`http://localhost:1420` by default), which is a normal http origin. Production builds serve it from `http://tauri.localhost` on Windows and Android but from the custom scheme `tauri://localhost` on macOS, Linux and iOS. Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so requests from `tauri://localhost` are blocked by the webview. On Windows and Android, `app.windows[].useHttpsScheme: true` switches the origin to `https://tauri.localhost`; both forms work.
* **CSP violation in the webview console**: the message names the blocked directive. Add `https://app.rybbit.io` there; the SDK only needs `connect-src`, the script tag also needs `script-src`.
* **Object vs string CSP**: `app.security.csp` accepts either a single policy string or the object form shown above. Do not mix the two.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Teachable (/fr/docs/guides/teachable)





Teachable adds tracking scripts through **Code Snippets** in the school admin, where the **Head Code Snippets** section places code inside the `<head>` of every page of your school. Code Snippets are available on the Builder plan and above.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Teachable [#add-the-snippet-to-teachable]

    1. In the school admin, go to **Site > Code Snippets**.
    2. Paste the snippet into the **Head Code Snippets** section, which applies to all pages and all users.
    3. Click **Save**.

    The **Logged In Snippets** and **Logged Out Snippets** sections restrict code to one audience. Leave them empty for Rybbit so students and prospects are tracked alike; if you only want to measure the public site, use **Logged Out Snippets** instead of the head section.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Code Snippets is missing from the Site menu**: it needs the Builder plan or higher. Schools on lower plans cannot add custom scripts.
* **Checkout and login pages are not tracked**: head code snippets do not apply to SSO-based login or checkout pages served from `sso.teachable.com`. Pages on your school domain, including the course area, are covered.
* **Snippet pasted into a lesson's Custom HTML block**: that block only affects one lesson. Use **Code Snippets** for site-wide tracking.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Thinkific (/fr/docs/guides/thinkific)





Thinkific adds custom scripts through the **Site Footer Code** field under **Settings > Code & Analytics**. The code runs at the bottom of every page, including the Course Player, and editing it is available on paid plans (Basic or higher). Placing the snippet in the footer rather than the head is fine: it loads with `defer`, so timing is the same.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Thinkific [#add-the-snippet-to-thinkific]

    1. In the admin dashboard, go to **Settings** and open the **Code & Analytics** tab.
    2. Paste the snippet into **Site Footer Code**.
    3. Save.

    See Thinkific's [Site Footer Code](https://support.thinkific.com/hc/en-us/articles/360030724953-Site-Footer-Code) article for the field's current limits. Lesson changes inside the Course Player happen without a page reload; Rybbit tracks them as pageviews automatically as the URL changes.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Field is read-only or missing**: editing Site Footer Code needs a paid plan (Basic or higher).
* **Checkout is not tracked**: Site Footer Code does not run on Performance Checkout pages, so purchases complete outside Rybbit's view. Track the enrolment from the first page a student lands on after checkout, or use a webhook on your side.
* **Community pages are not tracked**: pages where students post and comment, and direct-messaging pages, are excluded from Site Footer Code by default.
* **Per-page footer code**: individual site pages also accept footer code in their page settings. Keep the site-wide field as the single place for the snippet so pages are not tracked twice.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ThriveCart (/fr/docs/guides/thrivecart)





ThriveCart lets you add custom scripts to each checkout page, and its success page is where the purchase event goes. ThriveCart strips `data-*` attributes from script tags, so the site ID must travel in the script URL, as it does in the snippet below.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ThriveCart [#add-the-snippet-to-thrivecart]

    1. In your ThriveCart dashboard, open the checkout page you want to track.
    2. Open **Settings > Tracking**, the custom scripts section.
    3. Paste the snippet into the header scripts field and save.

    Repeat for each checkout page. If checkout runs on a subdomain such as `sales.yourdomain.com` and your main site uses the same site ID, both are tracked as one site, so funnels can follow a visitor from your site through to the purchase.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

ThriveCart also interferes with how inline events fire, so the success-page script below loads the tracker itself if it is missing, waits for it, and uses `sessionStorage` to send the event once per browser session even if the visitor refreshes or navigates back.

Add it to the checkout's **success page** and fill in the values at the top:

```html
<script>
(function () {
  var EVENT_NAME = "purchase";
  var PAYLOAD = { content_name: "Your Product Name", value: 97.0, currency: "USD" };
  var SITE_ID = "YOUR_SITE_ID";
  var SCRIPT_SRC = "https://app.rybbit.io/api/script.js?siteId=" + SITE_ID;

  // Send once per session, even on refresh or back navigation
  var SENT_KEY = "rybbit_" + EVENT_NAME + "_sent_v1";
  try {
    if (sessionStorage.getItem(SENT_KEY) === "1") return;
    sessionStorage.setItem(SENT_KEY, "1");
  } catch (e) {}

  function isReady() {
    return window.rybbit && typeof window.rybbit.event === "function";
  }
  function send() {
    window.rybbit.event(EVENT_NAME, PAYLOAD);
  }
  function waitThenSend(timeoutMs) {
    var start = Date.now();
    (function check() {
      if (isReady()) return send();
      if (Date.now() - start < timeoutMs) setTimeout(check, 150);
    })();
  }

  if (isReady()) return send();
  if (!document.querySelector('script[src="' + SCRIPT_SRC + '"]')) {
    var s = document.createElement("script");
    s.src = SCRIPT_SRC;
    s.defer = true;
    document.head.appendChild(s);
  }
  waitThenSend(8000);
})();
</script>
```

* `EVENT_NAME`: the event name, for example `purchase` or `checkout_complete`.
* `PAYLOAD`: `content_name` (product name), `value` (amount) and `currency` (`USD`, `GBP`, `EUR` and so on).
* `SITE_ID`: your Rybbit site ID.

Selling several products? The payload is fixed per page, so use a separate success page per product, or fill `PAYLOAD` from ThriveCart's dynamic variables where they are available.

## Troubleshooting [#troubleshooting]

* **Script attributes are stripped**: ThriveCart removes `data-*` attributes, so [script attributes](/docs/script#script-attributes) such as `data-skip-patterns` do not work here. Keep the site ID in the URL.
* **Duplicate purchase events**: the script is guarded by `sessionStorage`. If you still see duplicates, make sure the event script is on the success page only once, and clear session storage before testing again.
* **Script blocked**: if `script.js` never loads, try the footer scripts field instead of the header, or ask ThriveCart support to confirm custom scripts are enabled on your account.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# TYPO3 (/fr/docs/guides/typo3)





TYPO3 sitepackages build the page `<head>` from TypoScript rather than an HTML template, so the snippet is added as a `page.includeJS` entry in your sitepackage's `setup.typoscript`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to TYPO3 [#add-the-snippet-to-typo3]

    1. Open your main TypoScript setup file, usually `<sitepackage>/Configuration/TypoScript/setup.typoscript`. It is the file that already contains `page = PAGE`. The same TypoScript can also live in a TypoScript record in the backend.

    2. Add the script to the `page` object:

       ```
       page = PAGE
       page {
         includeJS {
           rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
           rybbit.defer = 1
         }
       }
       ```

       Because the Site ID is part of the URL, no `data-*` attribute is needed, so this works on every supported TYPO3 version. Per-include attributes on `includeJS` only exist in TYPO3 12.1+.

    3. To track production only, wrap the include in an `applicationContext` condition:

       ```
       [applicationContext == "Production"]
       page.includeJS.rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
       page.includeJS.rybbit.defer = 1
       [END]
       ```

    4. Optionally keep the Site ID and instance URL in `constants.typoscript` (or a TypoScript record) so the setup file can be committed without site-specific values:

       ```
       # constants.typoscript
       rybbit {
         host = https://app.rybbit.io
         siteId = YOUR_SITE_ID
       }

       # setup.typoscript
       page.includeJS.rybbit = {$rybbit.host}/api/script.js?siteId={$rybbit.siteId}
       page.includeJS.rybbit.defer = 1
       ```

    5. Deploy the sitepackage, or set `applicationContext` accordingly, and flush the TYPO3 caches.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Script not in the page source**: TYPO3 caches rendered pages. Flush caches from the backend toolbar or with `vendor/bin/typo3 cache:flush` after changing TypoScript.
* **Wrong TypoScript file**: if several files define `page`, check the resulting `page.includeJS` in the TypoScript object browser in the backend to see which definition wins.
* **Condition never matches**: the `applicationContext` is set through the `TYPO3_CONTEXT` environment variable. If it is unset, TYPO3 runs as `Production` and the script loads everywhere.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Umbraco (/fr/docs/guides/umbraco)





Umbraco renders pages with Razor templates stored as `.cshtml` files in the `Views` folder and edited in the backoffice under **Settings > Templates**. A fresh install has no templates until you create one, so the snippet goes into the master (layout) template that your page templates set as their `Layout`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Umbraco [#add-the-snippet-to-umbraco]

    1. In the backoffice, open the **Settings** section and expand **Templates**.
    2. Open the master template that the other templates use as their layout (named `Master&#x60; in Umbraco's own tutorial). If you have none yet, click &#x2A;*...** next to **Templates**, choose **Create**, and move the shared `<html>`, `<head>` and `<body>` markup into it.
    3. Add the tag before `</head>` and click **Save**:

    ```razor title="Views/Master.cshtml"
    @using Umbraco.Cms.Web.Common.PublishedModels;
    @inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
    @{
        Layout = null;
    }
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8" />
        <title>@Model.Name</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        @RenderBody()
    </body>
    </html>
    ```

    4. Check that each page template points at it, for example `Layout = "Master.cshtml";`. Templates with `Layout = null;` render their own `<head>` and need the tag added directly.

    Saving in the backoffice writes the same file to `Views/Master.cshtml` in the project, so you can also edit it in your IDE and commit it.

    To keep the site ID out of the template, put it in `appsettings.json` and read it with `@Configuration["Rybbit:SiteId"]` after injecting `IConfiguration`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Change not visible**: Razor views are compiled on first request; if you edited the file outside the backoffice on a published site, restart the app or redeploy. Also clear any output cache or CDN in front of the site.
* **Preview counts as visits**: the backoffice **Preview** button renders your template with unpublished content, so editors' previews are tracked like any other visit. Wrap the tag in `@if (!UmbracoContext.InPreviewMode) { ... }` to leave them out.
* **Backoffice is not tracked**: `/umbraco` is a separate app that does not use your templates, so editing time never appears in Rybbit.
* **Several master templates**: a multi-site install with one layout per site needs the tag in each, or in a partial view rendered from every layout with `@await Html.PartialAsync("Rybbit")`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Unbounce (/fr/docs/guides/unbounce)





Unbounce's **Script Manager** applies a script to every page on a domain, including pages you publish later, so that is where the snippet goes. If you only want to track a single Classic Builder page, the page-level **Javascripts** dialog works too.

<Callout type="warn">
  Custom scripts and pixels are not available on the Starter plan; you need Build or higher. Script Manager also requires a connected custom domain: it does not apply to pages on the `unbouncepages.com` test domain.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Unbounce [#add-the-snippet-to-unbounce]

    <Tabs items="[&#x22;Script Manager&#x22;, &#x22;Classic Builder page&#x22;]">
      <Tab>
        1. In the left menu, click **Settings**, then **Script Manager**.
        2. Click **Add a Script**, choose **Custom Script**, give it a name and click **Add Script Details**.
        3. Set **Placement** to **Head** and **Included on** to **All** (main pages and confirmation dialogs).
        4. Paste the snippet into the editor.
        5. Tick the domain(s) the script should apply to on the right, then click **Save Changes**.

        The script is added to every page on those domains and to new pages published there later. If a page does not pick it up, republish that page.
      </Tab>

      <Tab>
        1. Open the page in the Classic Builder and click **Javascripts** in the bottom-left corner.
        2. Give the script a name and set **Placement** to **Head**.
        3. Paste the snippet and click **Done**.
        4. **Save**, then **Publish** (or **Republish**) the page. Custom scripts do not run in the builder or in Preview, only on the published page.

        Smart Builder pages have no page-level script dialog; use Script Manager for those.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Form submission [#form-submission]

Unbounce exposes `window.ub.hooks`, an unofficial hook that runs after a lead is recorded. Add this as a second Script Manager script (or page script) with placement **Before Body End Tag** to send a `lead` event with the page name and variant:

```html
<script>
window.ub.hooks.afterFormSubmit.push(function () {
  if (window.rybbit) {
    window.rybbit.event("lead", {
      page: window.ub.page.name,
      variant: window.ub.page.variantId
    });
  }
});
</script>
```

`window.ub.page.name`, `window.ub.page.variantId` and `window.ub.page.id` are available on every Unbounce page, so you can compare A/B variants in Rybbit without any other setup.

## Troubleshooting [#troubleshooting]

* **Script runs twice**: a script that is both in Script Manager and on an individual page loads twice. Remove the page-level copy and keep the Script Manager one.
* **Nothing on `unbouncepages.com`**: Script Manager only applies to custom domains. Add the snippet at page level to test on the Unbounce test domain.
* **Script Manager missing**: the account is on the Starter plan, which does not include custom scripts.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# v0 (/fr/docs/guides/v0)





v0 generates Next.js apps, so there is no single `index.html` and no project setting for head code. The snippet goes into the root layout, `app/layout.tsx`, through a `next/script` tag that renders on every page. Ask v0 to add it or edit the file in the Code tab, then publish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to v0 [#add-the-snippet-to-v0]

    <Tabs items="[&#x22;Ask v0&#x22;, &#x22;Edit app/layout.tsx&#x22;]">
      <Tab>
        Paste this into the chat, with your site ID in place of the placeholder:

        ```text
        Add the Rybbit analytics script to the root layout (app/layout.tsx) using next/script with strategy="afterInteractive", so it loads on every page:
        https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
        ```

        Check the diff: the `<Script>` belongs in `app/layout.tsx`, not in a page or component.
      </Tab>

      <Tab>
        Select the **Code** tab in the preview toolbar, open `app/layout.tsx` and add the `Script` component inside `<body>`. The `defer` attribute from the snippet is not needed; the strategy handles timing.

        ```tsx title="app/layout.tsx"
        import Script from "next/script";

        export default function RootLayout({ children }: { children: React.ReactNode }) {
          return (
            <html lang="en">
              <body>
                {children}
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```

        Press **Cmd+S** / **Ctrl+S** to save.
      </Tab>
    </Tabs>

    Click **Publish** in the top right of the chat, then **Publish to Production**. Navigation through `<Link>` and `router.push()` is tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a client component. Guard the call, because v0 components can render on the server and the script loads after hydration.

```tsx title="components/signup-button.tsx"
"use client";

export function SignupButton() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Production has no script**: the preview updates on save, but the live site only changes after **Publish to Production**. Projects connected to GitHub go through a pull request that v0 merges before the production deployment runs.
* **v0 rewrote the layout**: a later prompt can regenerate `app/layout.tsx`. Add "keep the Rybbit Script tag in app/layout.tsx" to the project's custom instructions, and re-check the page source after large changes.
* **Pages Router**: if your project has `pages/` instead of `app/`, put the `Script` in `pages/_app.tsx` as shown in the [Next.js guide](/docs/guides/react/next-js).

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# VitePress (/fr/docs/guides/vitepress)





VitePress has a `head` option in `.vitepress/config.ts` that adds tags to every page, which is where the snippet goes. A custom theme is the fallback when you need to load it conditionally at runtime.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to VitePress [#add-the-snippet-to-vitepress]

    <Tabs items="[&#x22;Config file&#x22;, &#x22;Custom theme&#x22;]">
      <Tab>
        Edit `.vitepress/config.ts` (or `.js` / `.mts`) and add the tag to `head`:

        ```typescript filename=".vitepress/config.ts"
        import { defineConfig } from "vitepress";

        export default defineConfig({
          // ... your other config
          head: [
            [
              "script",
              {
                src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                defer: "",
              },
            ],
          ],
        });
        ```

        <Callout type="info">
          The empty string for `defer` is intentional. VitePress renders it as a boolean attribute.
        </Callout>

        To track production only, make `head` conditional:

        ```typescript filename=".vitepress/config.ts"
        const isProd = process.env.NODE_ENV === "production";

        export default defineConfig({
          head: isProd
            ? [["script", { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: "" }]]
            : [],
        });
        ```
      </Tab>

      <Tab>
        If you need runtime control, inject the tag from a custom theme. Create or edit `.vitepress/theme/index.ts`:

        ```typescript filename=".vitepress/theme/index.ts"
        import { type Theme } from "vitepress";
        import DefaultTheme from "vitepress/theme";

        export default {
          extends: DefaultTheme,
          enhanceApp() {
            if (typeof window === "undefined") return;

            const el = document.createElement("script");
            el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
            el.defer = true;
            document.head.appendChild(el);
          },
        } satisfies Theme;
        ```

        The `window` check keeps the injector out of the server-side build.
      </Tab>
    </Tabs>

    VitePress navigates between pages client-side. Rybbit picks up those History API changes as pageviews, so no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in `vitepress dev`**: if you used the `isProd` guard, the tag only renders in `vitepress build`. Remove the guard to test locally.
* **Pageviews stop after navigation**: check the browser console for errors thrown by other `head` scripts or theme code; an exception during route change can block Rybbit's listener.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Webflow (/fr/docs/guides/webflow)





Webflow accepts custom `<head>` code either site-wide in **Site settings → Custom code** or per page in the page settings. Either way the code only reaches the live site when you publish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Webflow [#add-the-snippet-to-webflow]

    <Tabs items="[&#x22;Site-wide&#x22;, &#x22;Single page&#x22;]">
      <Tab value="Site-wide">
        1. Open your project and go to **Site settings → Custom code**.
        2. Paste the snippet into **Head code**.
        3. Click **Save**, then **Publish** the site.
      </Tab>

      <Tab value="Single page">
        Use this when you only want to track specific pages.

        1. In the Designer, open the page's **Settings** (cog icon next to the page name).
        2. Scroll to **Custom code** and paste the snippet into **Inside `<head>` tag**.
        3. Click **Save**, then **Publish** the site.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Give the element an **ID** in the Designer (**Settings** panel → **General** → **ID**), then attach a listener in **Site settings → Custom code → Footer code** or in an **Embed** element on that page:

```html
<script>
  document.addEventListener("DOMContentLoaded", function () {
    var button = document.getElementById("my-special-button");
    if (!button) return;
    button.addEventListener("click", function () {
      window.rybbit?.event("button_click", {
        button_id: "my-special-button",
        page_path: window.location.pathname,
      });
    });
  });
</script>
```

The same pattern works for a Form Block's `submit` event. Webflow handles form submission itself, so this fires on the submit attempt, not on confirmed success.

## Troubleshooting [#troubleshooting]

* **Changes not showing on the live site**: custom code is staged until you **Publish**. Check the published site, not the Designer preview.
* **Interactions that show or hide sections** without changing the URL produce a single pageview. Track those states as custom events, or call `window.rybbit.pageview()` from your own script when they appear.
* **Scripts that read the DOM** belong in **Footer code**, not **Head code**, so the elements exist when they run.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Weebly (/fr/docs/guides/weebly)





Weebly (now part of Square) has site-wide **Header Code** and **Footer Code** fields under its SEO settings. Header code is printed into the `<head>` of every page, so the snippet goes there and no theme edits are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Weebly [#add-the-snippet-to-weebly]

    1. Open your site in the Weebly editor and go to **Settings > SEO**.
    2. Paste the snippet into **Header Code** and click **Save**.
    3. Click **Publish**. Header code changes only reach the live site after you publish.

    If your editor has no **Settings** tab, the same header-code option is under **Website > General Settings** in the Square dashboard.

    Site-level header code covers every page, including blog posts. Each page also has its own **Header Code** box in its page settings; that one is for page-specific code and is not needed for the snippet.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the page source**: the site was not republished. Click **Publish** after every change to header code.
* **Snippet appears twice**: it was added both site-wide and on individual pages. Keep only the site-level entry under **Settings > SEO**.
* **Footer Code instead of Header Code**: both fields are included on every page, so the snippet works from either, but the footer loads later and misses visitors who leave early.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Wix (/fr/docs/guides/wix)





Wix adds third-party scripts through the **Custom Code** panel in the site dashboard, where you choose which pages load the code and where in the document it goes.

<Callout type="warn">
  Custom code requires a **Wix Premium plan** and a **connected domain**. It is not available on free Wix sites.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Wix [#add-the-snippet-to-wix]

    1. Open your site's dashboard and go to **Settings**.
    2. Open **Custom Code** (under **Advanced**). Older dashboards list it as **Tracking Tools & Analytics** under **Marketing & SEO**.
    3. Click **+ Add Custom Code** and paste the snippet into the code box.
    4. Name the code, for example `Rybbit`.
    5. Under **Add Code to Pages**, choose **All pages** and **Load code once**. The script tracks Wix's client-side navigation itself, so loading it on every page change would inject it repeatedly.
    6. Under **Place Code in**, choose **Head**.
    7. Click **Apply**.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Custom Code is missing from Settings**: the site has no Premium plan or no connected domain. Both are required before the panel appears.
* **Duplicate pageviews**: the code was added with **Load code on each new page**. Edit the entry and switch to **Load code once**.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# WooCommerce (/fr/docs/guides/woocommerce)





WooCommerce runs on WordPress, so the snippet goes in the same way as on any WordPress site. What this guide adds is the WooCommerce action hooks that send purchases, add-to-carts, product views and checkouts to Rybbit as custom events.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to WooCommerce [#add-the-snippet-to-woocommerce]

    Follow the [WordPress guide](/docs/guides/wordpress) to add the snippet. If you plan to track the e-commerce events below, use the `functions.php` or mini-plugin method there: the event hooks are PHP and belong in the same file.

    ```php
    function rybbit_add_tracking_script() {
        ?>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        <?php
    }
    add_action( 'wp_head', 'rybbit_add_tracking_script' );
    ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

WooCommerce fires PHP action hooks at each stage of the shopping flow. The snippets below print a small inline script from those hooks. They wait for `DOMContentLoaded` because the tracking script is loaded with `defer`, so `window.rybbit` does not exist while the page is still parsing.

<Callout type="warn">
  Add these to your &#x2A;*child theme's `functions.php`** or a site-specific plugin, never to the parent theme.
</Callout>

#### Purchase [#purchase]

`woocommerce_thankyou` fires on the order-received page with the order ID.

```php
add_action( 'woocommerce_thankyou', 'rybbit_track_purchase', 10, 1 );
function rybbit_track_purchase( $order_id ) {
    $order = wc_get_order( $order_id );
    if ( ! $order ) {
        return;
    }

    $items = array();
    foreach ( $order->get_items() as $item ) {
        $product = $item->get_product();
        $items[] = array(
            'item_id'   => $product && $product->get_sku() ? $product->get_sku() : $item->get_product_id(),
            'item_name' => $item->get_name(),
            'price'     => (float) $order->get_line_subtotal( $item, false, false ),
            'quantity'  => (int) $item->get_quantity(),
        );
    }

    $purchase = array(
        'transaction_id' => $order->get_order_number(),
        'value'          => (float) $order->get_total(),
        'tax'            => (float) $order->get_total_tax(),
        'shipping'       => (float) $order->get_shipping_total(),
        'currency'       => $order->get_currency(),
        'items'          => $items,
    );
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function () {
        window.rybbit.event('purchase', <?php echo wp_json_encode( $purchase ); ?>);
    });
    </script>
    <?php
}
```

Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.

#### Add to cart [#add-to-cart]

Two hooks cover both paths: the product-page form submit, and WooCommerce's `added_to_cart` jQuery event for AJAX buttons on shop and category pages.

```php
// Single product page: track on form submit
add_action( 'woocommerce_after_add_to_cart_button', 'rybbit_track_add_to_cart' );
function rybbit_track_add_to_cart() {
    global $product;
    if ( ! $product instanceof WC_Product ) {
        return;
    }
    $data = array(
        'item_id'   => $product->get_sku() ? $product->get_sku() : $product->get_id(),
        'item_name' => $product->get_name(),
        'price'     => (float) $product->get_price(),
        'currency'  => get_woocommerce_currency(),
    );
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function () {
        var form = document.querySelector('form.cart');
        if (!form) return;
        form.addEventListener('submit', function () {
            var data = <?php echo wp_json_encode( $data ); ?>;
            var qty = form.querySelector('input.qty');
            data.quantity = qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1;
            window.rybbit.event('add_to_cart', data);
        });
    });
    </script>
    <?php
}

// AJAX add-to-cart buttons on shop and category pages
add_action( 'wp_footer', 'rybbit_track_ajax_add_to_cart' );
function rybbit_track_ajax_add_to_cart() {
    if ( is_admin() ) {
        return;
    }
    ?>
    <script>
    jQuery(document.body).on('added_to_cart', function (event, fragments, cartHash, $button) {
        if (!$button || !$button.length) return;
        window.rybbit.event('add_to_cart', {
            item_id: $button.data('product_id'),
            quantity: $button.data('quantity') || 1,
            source: 'ajax_add_to_cart'
        });
    });
    </script>
    <?php
}
```

The AJAX handler only sees the product ID and quantity from the button's `data-*` attributes. Add attributes to the button in your theme if you also want name and price.

#### View product and begin checkout [#view-product-and-begin-checkout]

The same pattern works for the remaining hooks:

* `woocommerce_after_single_product_summary` runs on product pages. Guard with `is_product()`, then send `view_item` with `item_id`, `item_name`, `price` and `currency` from the global `$product`.
* `woocommerce_before_checkout_form` runs on the checkout page. Build `begin_checkout` from `WC()->cart`: loop over `get_cart()` for the items (each `$cart_item['data']` is the product, `$cart_item['quantity']` the quantity), with `value` from `$cart->get_total( 'edit' )` and `currency` from `get_woocommerce_currency()`.

## Troubleshooting [#troubleshooting]

* **Events fire before the tracker loads**: keep the tracking snippet in `wp_head` and the `DOMContentLoaded` wrapper in place. Deferred scripts run before `DOMContentLoaded`, so `window.rybbit` is ready by then; calling it from a bare inline script drops the event.
* **AJAX carts and mini-carts**: themes that update the cart without a page load never hit the PHP hooks, so rely on the `added_to_cart` listener for those and test each add-to-cart path.
* **Other analytics plugins**: plugins that also print e-commerce data layers can conflict. Test with a real order after enabling both.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# WordPress (/fr/docs/guides/wordpress)





WordPress has no built-in header-code setting, so the snippet goes in through a plugin such as **WPCode** or through your theme's `functions.php` or `header.php`. Every method below works on self-hosted WordPress.org sites; on WordPress.com you need the Business plan or higher before you can install plugins or add custom JavaScript.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to WordPress [#add-the-snippet-to-wordpress]

    <Callout type="warn">
      If you edit theme files, edit a **child theme**. Changes to a parent theme's `functions.php` or `header.php` are lost on the next theme update.
    </Callout>

    <Tabs items="[&#x22;WPCode&#x22;, &#x22;functions.php&#x22;, &#x22;header.php&#x22;, &#x22;Mini plugin&#x22;]">
      <Tab>
        WPCode (formerly Insert Headers and Footers) is the recommended method: it survives theme updates, works with page builders, and is available on WordPress.com Business plans.

        1. Go to **Plugins > Add New**, search for "WPCode", then install and activate it.
        2. Go to **Code Snippets > Header & Footer** (**Settings > Insert Headers and Footers** in older versions).
        3. Paste the snippet into the **Header** box and click **Save Changes**.
      </Tab>

      <Tab>
        1. Go to **Appearance > Theme File Editor** and open your child theme's `functions.php`.
        2. Add this to the end of the file, replacing `YOUR_SITE_ID`:

        ```php
        function rybbit_add_tracking_script() {
            ?>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
            <?php
        }
        add_action( 'wp_head', 'rybbit_add_tracking_script' );
        ```

        3. Save the file.
      </Tab>

      <Tab>
        1. Go to **Appearance > Theme File Editor** and open your child theme's `header.php`.
        2. Paste the snippet just before the closing `</head>` tag:

        ```html
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        3. Save the file.
      </Tab>

      <Tab>
        A one-file plugin keeps the snippet in place through theme changes without touching theme files.

        1. Over FTP/SFTP or a file-manager plugin, create the folder `/wp-content/plugins/rybbit-analytics/`.
        2. Inside it, create `rybbit-analytics.php` with this content, replacing `YOUR_SITE_ID`:

        ```php
        <?php
        /**
         * Plugin Name: Rybbit Analytics
         * Description: Adds the Rybbit tracking script to every page
         * Version: 1.0
         */

        function rybbit_add_tracking_script() {
            ?>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
            <?php
        }
        add_action( 'wp_head', 'rybbit_add_tracking_script' );
        ```

        3. Go to **Plugins** and activate **Rybbit Analytics**.
      </Tab>
    </Tabs>

    Running WooCommerce? Once the snippet is in place, see the [WooCommerce guide](/docs/guides/woocommerce) for purchase and add-to-cart events.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Caching plugins**: after saving the snippet, purge WP Super Cache, W3 Total Cache, LiteSpeed Cache or whichever cache plugin you run, plus any CDN cache such as Cloudflare, before you check the page source.
* **Script optimisers**: "Delay JavaScript execution" features in WP Rocket, Perfmatters and FlyingPress rebuild script tags and drop `data-*` attributes, which is why the snippet passes the site ID in the URL (`?siteId=`). If tracking still fails, exclude `app.rybbit.io` from optimisation: Autoptimize's exclusion list, WP Rocket's JavaScript optimisation and delay-JS exclusions, Perfmatters / FlyingPress delay-JS exclusions, LiteSpeed Cache JS excludes, SG Optimizer combine/minify.
* **Page builders** (Elementor, Divi, WPBakery, Beaver Builder): add the snippet with WPCode rather than a builder's custom HTML block. Builders sanitise HTML and can strip attributes from script tags.
* **Security plugins**: Wordfence, Sucuri and similar plugins can block external scripts. Add `app.rybbit.io` to the allowlist.
* **WordPress.com plans**: Free, Personal and Premium plans cannot add custom JavaScript. Upgrade to Business or eCommerce and use the WPCode method.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Zola (/fr/docs/guides/zola)





Zola pages extend a base Tera template, normally `templates/base.html`, so the snippet goes in that file's `<head>`. Keep the site ID in the `[extra]` section of `config.toml`, which every template can read as `config.extra`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Zola [#add-the-snippet-to-zola]

    1. Add your site ID under `[extra]` in `config.toml`. `rybbit_instance_url` is only needed if you self-host:

       ```toml title="config.toml"
       [extra]
       rybbit_site_id = "YOUR_SITE_ID"
       rybbit_instance_url = "https://app.rybbit.io"
       ```

    2. Open `templates/base.html` and add the tag inside `<head>`. The `config.mode` check keeps the script out of `zola serve`, so local development is not tracked:

       ```html title="templates/base.html"
       <head>
         ...
         {% if config.mode == "build" %}
           <script src="{{ config.extra.rybbit_instance_url }}/api/script.js?siteId={{ config.extra.rybbit_site_id }}" defer></script>
         {% endif %}
       </head>
       ```

       If a theme owns `base.html`, copy it from `themes/<theme>/templates/base.html` into your own `templates/` directory first. A template in your site with the same name overrides the theme's copy, so the theme can be updated without losing the change.

    3. Build and deploy the generated `public/` directory:

       ```bash
       zola build
       ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `zola serve` sets `config.mode` to `serve`, so the guard removes the tag. Check the output of `zola build` instead.
* **`config.mode` is not defined**: older Zola releases do not expose it. Upgrade, or drop the `if` block and accept local pageviews.
* **Pages without the tag**: templates that do not `{% extends "base.html" %}` (a custom `404.html`, or a section template that builds its own `<head>`) need the tag added separately.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Astro Proxy Setup (/fr/docs/proxy-guide/astro)





Astro's middleware feature makes it simple to proxy Rybbit tracking. This guide shows how to set up server-side request proxying in your Astro application.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Astro middleware allows you to intercept and modify requests before they're handled, making it perfect for creating a transparent analytics proxy.

**What you'll achieve:**

* Proxy Rybbit endpoints through your Astro site
* Forward necessary headers for accurate tracking
* Simple configuration in `astro.config.mjs`
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Astro 2.0 or later (with SSR or hybrid rendering enabled)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

<Callout type="warn">
  This guide requires SSR (Server-Side Rendering) or hybrid mode. Static sites cannot proxy requests server-side. For static sites on platforms like Vercel or Netlify, use their platform-specific proxy configurations.
</Callout>

## Implementation [#implementation]

<Steps>
  ### Enable SSR in Astro [#enable-ssr-in-astro]

  Update `astro.config.mjs` to enable SSR:

  ```javascript
  // astro.config.mjs
  import { defineConfig } from 'astro/config';
  import node from '@astrojs/node';

  export default defineConfig({
    output: 'server', // or 'hybrid'
    adapter: node({
      mode: 'standalone',
    }),
  });
  ```

  Install the Node adapter if not already installed:

  ```bash
  npm install @astrojs/node
  ```

  ### Configure Environment Variables [#configure-environment-variables]

  Create or update `.env`:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  ### Create Middleware [#create-middleware]

  Create `src/middleware.ts` (or `.js` for JavaScript):

  ```typescript
  // src/middleware.ts
  import type { MiddlewareHandler } from 'astro';

  const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';

  export const onRequest: MiddlewareHandler = async (context, next) => {
    const { request } = context;
    const url = new URL(request.url);

    // Check if this is an analytics request
    if (url.pathname.startsWith('/analytics/')) {
      return proxyToRybbit(request, url.pathname);
    }

    // Continue with normal request handling
    return next();
  };

  async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
    try {
      // Map paths: /analytics/* → /api/*
      let rybbitPath = pathname.replace('/analytics/', '/api/');

      const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;

      // Get client IP from headers
      const forwardedFor = request.headers.get('x-forwarded-for');
      const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';

      // Forward request
      const proxyHeaders = new Headers(request.headers);
      proxyHeaders.set('X-Real-IP', clientIp);
      proxyHeaders.set('X-Forwarded-For', clientIp);

      const response = await fetch(rybbitUrl, {
        method: request.method,
        headers: proxyHeaders,
        body: request.method !== 'GET' ? await request.text() : undefined,
      });

      // Return proxied response
      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
      });
    } catch (error) {
      console.error('Rybbit proxy error:', error);
      return new Response('Analytics proxy error', { status: 500 });
    }
  }
  ```

  For JavaScript projects:

  ```javascript
  // src/middleware.js
  const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';

  export const onRequest = async (context, next) => {
    const { request } = context;
    const url = new URL(request.url);

    if (url.pathname.startsWith('/analytics/')) {
      return proxyToRybbit(request, url.pathname);
    }

    return next();
  };

  async function proxyToRybbit(request, pathname) {
    try {
      // Map paths: /analytics/* → /api/*
      let rybbitPath = pathname.replace('/analytics/', '/api/');

      const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;
      const forwardedFor = request.headers.get('x-forwarded-for');
      const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';

      const proxyHeaders = new Headers(request.headers);
      proxyHeaders.set('X-Real-IP', clientIp);
      proxyHeaders.set('X-Forwarded-For', clientIp);

      const response = await fetch(rybbitUrl, {
        method: request.method,
        headers: proxyHeaders,
        body: request.method !== 'GET' ? await request.text() : undefined,
      });

      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
      });
    } catch (error) {
      console.error('Rybbit proxy error:', error);
      return new Response('Analytics proxy error', { status: 500 });
    }
  }
  ```

  ### Update Your Layout [#update-your-layout]

  Add the tracking script to your layout:

  ```astro
  ---
  // src/layouts/Layout.astro
  const { title } = Astro.props;
  ---

  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width" />
      <title>{title}</title>

      <!-- Rybbit Analytics -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
    </head>
    <body>
      <slot />
    </body>
  </html>
  ```

  ### Start Development Server [#start-development-server]

  ```bash
  npm run dev
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Open your site** in a browser with Developer Tools
  2. **Check Network tab**: Requests should go to `/analytics/*`
  3. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Astro middleware intercepts requests before they're processed:

1. Request to `/analytics/script.js` enters middleware
2. Middleware proxies to `https://app.rybbit.io/api/script.js`
3. Client IP headers are preserved
4. Response is returned to browser

## Advanced Configuration [#advanced-configuration]

### Caching with Astro [#caching-with-astro]

Add caching for scripts:

```typescript
// src/middleware.ts
const cache = new Map<string, { response: Response; timestamp: number }>();
const CACHE_TTL = 3600000; // 1 hour in milliseconds

async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
  // Cache GET requests for scripts
  if (request.method === 'GET' && pathname.endsWith('.js')) {
    const cached = cache.get(pathname);

    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
      return cached.response.clone();
    }
  }

  // ... proxy logic

  // Cache the response
  if (request.method === 'GET' && pathname.endsWith('.js')) {
    cache.set(pathname, {
      response: response.clone(),
      timestamp: Date.now(),
    });
  }

  return response;
}
```

### Conditional Proxying [#conditional-proxying]

Only proxy in production:

```typescript
export const onRequest: MiddlewareHandler = async (context, next) => {
  const { request } = context;
  const url = new URL(request.url);

  // Only proxy in production
  if (import.meta.env.PROD && url.pathname.startsWith('/analytics/')) {
    return proxyToRybbit(request, url.pathname);
  }

  return next();
};
```

### Error Logging [#error-logging]

Add detailed error logging:

```typescript
async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
  try {
    // ... proxy logic
  } catch (error) {
    const errorDetails = {
      message: error instanceof Error ? error.message : 'Unknown error',
      pathname,
      method: request.method,
      timestamp: new Date().toISOString(),
    };

    console.error('Rybbit proxy error:', errorDetails);

    // Return error response
    return new Response(JSON.stringify({ error: 'Analytics proxy error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}
```

## Troubleshooting [#troubleshooting]

### Middleware not running [#middleware-not-running]

**Problem**: Requests bypass middleware.

**Solution**:

1. Ensure SSR or hybrid mode is enabled in `astro.config.mjs`
2. Verify middleware file is in `src/middleware.ts` (not in subdirectory)
3. Check adapter is installed: `npm install @astrojs/node`

### Static build issues [#static-build-issues]

**Problem**: Build fails or proxy doesn't work in production.

**Solution**:
Middleware requires server-side rendering. Ensure:

```javascript
// astro.config.mjs
export default defineConfig({
  output: 'server', // Required for middleware
  adapter: node({
    mode: 'standalone',
  }),
});
```

### Environment variables not loading [#environment-variables-not-loading]

**Problem**: `RYBBIT_HOST` is undefined.

**Solution**:

1. Check `.env` file is in project root
2. Use `import.meta.env.RYBBIT_HOST` (not `process.env`)
3. For production, set environment variables in your hosting platform

## Deployment [#deployment]

### Vercel [#vercel]

Deploy with Vercel adapter:

```bash
npm install @astrojs/vercel
```

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});
```

### Netlify [#netlify]

Deploy with Netlify adapter:

```bash
npm install @astrojs/netlify
```

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify/functions';

export default defineConfig({
  output: 'server',
  adapter: netlify(),
});
```

### Node.js Server [#nodejs-server]

For self-hosting:

```bash
npm run build
node ./dist/server/entry.mjs
```

## Related Resources [#related-resources]

* [Astro Integration Guide](/docs/guides/astro) - General Astro integration
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Astro Middleware](https://docs.astro.build/en/guides/middleware/) - Official Astro docs


# Caddy Proxy Setup (/fr/docs/proxy-guide/caddy)





Caddy is a powerful web server with automatic HTTPS that makes reverse proxying simple and secure. This guide shows how to configure Caddy to proxy Rybbit tracking through your own domain.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Caddy's `reverse_proxy` directive makes it incredibly easy to proxy requests. Combined with automatic HTTPS via Let's Encrypt, Caddy provides a secure, low-configuration solution for proxying analytics.

**What you'll achieve:**

* Automatic HTTPS with Let's Encrypt
* Simple reverse proxy configuration
* Header forwarding for accurate tracking
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Caddy installed (version 2.0 or later)
* Domain pointing to your server
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID (found in your dashboard)

<Callout type="info">
  Caddy automatically obtains and renews SSL certificates from Let's Encrypt. No manual SSL configuration needed!
</Callout>

## Implementation [#implementation]

<Steps>
  ### Configure Caddyfile [#configure-caddyfile]

  Add or update your Caddyfile with the analytics proxy configuration:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'Simplified with Handle Path']">
    <Tab>
      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          # Your main site configuration
          # ...

          # Rybbit Analytics Proxy
          # Main tracking script
          handle /analytics/script.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up X-Forwarded-Proto {scheme}
              }
              rewrite * /api/script.js
          }

          # Session replay script
          handle /analytics/replay.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/replay.js
          }

          # Web Vitals metrics script
          handle /analytics/metrics.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/metrics.js
          }

          # Event tracking endpoint
          handle /analytics/track {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/track
          }

          # User identification endpoint
          handle /analytics/identify {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/identify
          }

          # Session replay recording
          handle /analytics/session-replay/record/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/session-replay/record{path}
          }

          # Site configuration
          handle /analytics/site/tracking-config/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/site/tracking-config{path}
          }
      }
      ```

      <Callout type="info">
        Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
      </Callout>
    </Tab>

    <Tab>
      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          # Main tracking script
          handle /analytics/script.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/script.js
          }

          # Event tracking
          handle /analytics/track {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/track
          }
      }
      ```
    </Tab>

    <Tab>
      Caddy 2.4+ supports a cleaner syntax with `handle_path`:

      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          handle_path /analytics/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api{uri}
          }
      }
      ```

      This proxies all `/analytics/*` requests to `https://app.rybbit.io/api/*`.
    </Tab>
  </Tabs>

  ### Validate Caddyfile [#validate-caddyfile]

  Test your configuration for syntax errors:

  ```bash
  caddy validate --config /etc/caddy/Caddyfile
  ```

  You should see:

  ```
  Valid configuration
  ```

  ### Reload Caddy [#reload-caddy]

  Apply the changes by reloading Caddy:

  ```bash
  sudo caddy reload --config /etc/caddy/Caddyfile
  ```

  Or if using systemd:

  ```bash
  sudo systemctl reload caddy
  ```

  <Callout type="info">
    Caddy will automatically obtain an SSL certificate from Let's Encrypt on first request if one doesn't exist.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to load the script from your proxied domain:

  ```html
  <!DOCTYPE html>
  <html>
  <head>
      <!-- ... other head elements -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      <!-- Your content -->
  </body>
  </html>
  ```

  Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.

  ### Verify the Setup [#verify-the-setup]

  Test your configuration:

  1. **Check Caddy is running**:
     ```bash
     sudo systemctl status caddy
     ```

  2. **Test script loading**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see `HTTP/2 200` with `content-type: application/javascript`.

  3. **Open your website** in a browser with Developer Tools and verify:
     * Script loads from `/analytics/script.js`
     * Tracking requests go to `/analytics/track`
     * Data appears in Rybbit dashboard
</Steps>

## How It Works [#how-it-works]

Caddy's `reverse_proxy` directive forwards requests to Rybbit's servers:

1. Browser requests `https://yourdomain.com/analytics/script.js`
2. Caddy matches the handle block
3. Rewrites the path to `/api/script.js`
4. Forwards to `https://app.rybbit.io/api/script.js` with proper headers
5. Returns response to browser

The Rybbit script auto-detects it's being served from your domain and sends all tracking to your domain's endpoints.

## Advanced Configuration [#advanced-configuration]

### Caching with Cache-Control [#caching-with-cache-control]

Add caching headers for better performance:

```txt
yourdomain.com {
    # Scripts - cache for 1 hour
    handle /analytics/script.js {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/script.js
        header Cache-Control "public, max-age=3600"
    }

    # Config - cache for 5 minutes
    handle /analytics/site/tracking-config/* {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/site/tracking-config{path}
        header Cache-Control "public, max-age=300"
    }

    # Tracking - no cache
    handle /analytics/track {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/track
        header Cache-Control "no-store"
    }
}
```

### Subdomain Proxy [#subdomain-proxy]

Use a dedicated subdomain for analytics:

```txt
# /etc/caddy/Caddyfile

analytics.yourdomain.com {
    reverse_proxy https://app.rybbit.io {
        header_up Host app.rybbit.io
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
    }
    rewrite * /api{uri}
}
```

Then use:

```html
<script src="https://analytics.yourdomain.com/script.js" data-site-id="123"></script>
```

### Request Size Limits [#request-size-limits]

For session replay, increase max body size:

```txt
yourdomain.com {
    # Increase request body limit for session replay
    handle /analytics/session-replay/record/* {
        request_body {
            max_size 10MB
        }
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/session-replay/record{path}
    }
}
```

### Environment-Based Configuration [#environment-based-configuration]

Use Caddy's environment variable support:

```txt
# /etc/caddy/Caddyfile

{$DOMAIN:yourdomain.com} {
    handle_path /analytics/* {
        reverse_proxy {$RYBBIT_HOST:https://app.rybbit.io} {
            header_up Host {upstream_hostport}
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api{uri}
    }
}
```

Then set environment variables:

```bash
export DOMAIN=yourdomain.com
export RYBBIT_HOST=https://app.rybbit.io
caddy run
```

### Rate Limiting [#rate-limiting]

Protect your proxy with rate limiting using the `rate_limit` plugin:

```txt
yourdomain.com {
    handle /analytics/track {
        rate_limit {
            zone analytics {
                key {remote_host}
                events 100
                window 1m
            }
        }
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/track
    }
}
```

<Callout type="warn">
  The `rate_limit` directive requires the [caddy-ratelimit plugin](https://github.com/mholt/caddy-ratelimit). Install with: `xcaddy build --with github.com/mholt/caddy-ratelimit`
</Callout>

## Troubleshooting [#troubleshooting]

### Certificate errors [#certificate-errors]

**Problem**: Caddy fails to obtain SSL certificate.

**Solution**:

1. Verify domain points to your server (DNS)
2. Check ports 80 and 443 are open
3. Ensure no other process is using port 443
4. Check Caddy logs: `journalctl -u caddy -f`

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show same location.

**Solution**:
Ensure you're forwarding client IP:

```txt
reverse_proxy https://app.rybbit.io {
    header_up X-Real-IP {remote_host}
    header_up X-Forwarded-For {remote_host}
}
```

### 502 Bad Gateway [#502-bad-gateway]

**Problem**: Caddy returns 502 when accessing analytics endpoints.

**Solution**:

1. Verify Rybbit backend is accessible:
   ```bash
   curl -I https://app.rybbit.io/api/script.js
   ```
2. Check Caddy logs for errors:
   ```bash
   journalctl -u caddy -n 50
   ```

### Path rewriting not working [#path-rewriting-not-working]

**Problem**: Requests go to wrong Rybbit endpoints.

**Solution**:
Use the `rewrite` directive correctly:

```txt
handle /analytics/script.js {
    rewrite * /api/script.js  # Rewrite before reverse_proxy
    reverse_proxy https://app.rybbit.io {
        # ... headers
    }
}
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Framework-agnostic concepts
* [Caddy Documentation](https://caddyserver.com/docs/) - Official Caddy docs
* [Caddy reverse\_proxy](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) - Reverse proxy directive docs


# Cloudflare Workers Proxy Setup (/fr/docs/proxy-guide/cloudflare-workers)





Cloudflare Workers provide a serverless way to proxy Rybbit tracking at the edge, close to your users worldwide. This delivers excellent performance with minimal configuration.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Cloudflare Workers run on Cloudflare's global network, intercepting and proxying requests before they reach your origin server. This makes them perfect for analytics proxying with built-in caching and ultra-low latency.

**What you'll achieve:**

* Edge-based proxying in 300+ cities worldwide
* Automatic caching with Cloudflare's Cache API
* Sub-10ms latency for most requests
* Zero server infrastructure needed

## Prerequisites [#prerequisites]

* Cloudflare account with your domain
* Workers enabled on your account (free tier available)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Create Worker [#create-worker]

  Log in to Cloudflare Dashboard and create a new Worker:

  1. Go to **Workers & Pages** → **Create application** → **Create Worker**
  2. Name it `rybbit-proxy` (or your preferred name)
  3. Click **Deploy** to create the worker

  ### Update Worker Code [#update-worker-code]

  Replace the default code with the proxy implementation:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'With Environment Variables']">
    <Tab>
      ```javascript
      // Cloudflare Worker for Rybbit Analytics Proxy

      const RYBBIT_HOST = 'https://app.rybbit.io';

      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request));
      });

      async function handleRequest(request) {
        const url = new URL(request.url);

        // Only proxy /analytics/* paths
        if (!url.pathname.startsWith('/analytics/')) {
          // Pass through to origin
          return fetch(request);
        }

        try {
          return await proxyToRybbit(request, url);
        } catch (error) {
          console.error('Proxy error:', error);
          return new Response('Analytics proxy error', { status: 500 });
        }
      }

      async function proxyToRybbit(request, url) {
        // Map paths: /analytics/* → /api/*
        let rybbitPath = url.pathname.replace('/analytics/', '/api/');

        // Build Rybbit URL
        const rybbitUrl = new URL(rybbitPath, RYBBIT_HOST);
        rybbitUrl.search = url.search; // Preserve query params

        // Get client IP
        const clientIp = request.headers.get('CF-Connecting-IP') ||
                         request.headers.get('X-Forwarded-For') ||
                         '0.0.0.0';

        // Build request headers
        const proxyHeaders = new Headers(request.headers);
        proxyHeaders.set('X-Real-IP', clientIp);
        proxyHeaders.set('X-Forwarded-For', clientIp);
        proxyHeaders.delete('CF-Connecting-IP'); // Remove Cloudflare internal header

        // Build proxy request
        const proxyRequest = new Request(rybbitUrl, {
          method: request.method,
          headers: proxyHeaders,
          body: request.method !== 'GET' && request.method !== 'HEAD' ? request.body : undefined,
        });

        // Check cache for GET requests
        if (request.method === 'GET') {
          const cache = caches.default;
          let response = await cache.match(proxyRequest);

          if (response) {
            // Return cached response
            return new Response(response.body, {
              status: response.status,
              statusText: response.statusText,
              headers: {
                ...Object.fromEntries(response.headers),
                'X-Cache-Status': 'HIT',
              },
            });
          }
        }

        // Fetch from Rybbit
        const response = await fetch(proxyRequest);

        // Cache scripts for 1 hour
        if (request.method === 'GET' && url.pathname.match(/\.(js)$/)) {
          const cacheResponse = new Response(response.body, response);
          cacheResponse.headers.set('Cache-Control', 'public, max-age=3600');
          cacheResponse.headers.set('X-Cache-Status', 'MISS');

          // Clone and cache
          const cache = caches.default;
          await cache.put(proxyRequest, cacheResponse.clone());

          return cacheResponse;
        }

        // Return non-cacheable response
        return new Response(response.body, {
          status: response.status,
          statusText: response.statusText,
          headers: response.headers,
        });
      }
      ```
    </Tab>

    <Tab>
      ```javascript
      // Minimal Cloudflare Worker for Rybbit

      const RYBBIT_HOST = 'https://app.rybbit.io';

      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request));
      });

      async function handleRequest(request) {
        const url = new URL(request.url);

        // Only proxy /analytics/script.js and /analytics/track
        if (url.pathname === '/analytics/script.js' || url.pathname === '/analytics/track') {
          const rybbitPath = url.pathname.replace('/analytics/', '/api/');
          const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;

          const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

          const proxyHeaders = new Headers(request.headers);
          proxyHeaders.set('X-Real-IP', clientIp);
          proxyHeaders.set('X-Forwarded-For', clientIp);

          return fetch(rybbitUrl, {
            method: request.method,
            headers: proxyHeaders,
            body: request.method === 'POST' ? request.body : undefined,
          });
        }

        // Pass through to origin
        return fetch(request);
      }
      ```
    </Tab>

    <Tab>
      Using Workers secrets for configuration:

      ```javascript
      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request, event.env));
      });

      async function handleRequest(request, env) {
        const RYBBIT_HOST = env.RYBBIT_HOST || 'https://app.rybbit.io';
        const url = new URL(request.url);

        if (!url.pathname.startsWith('/analytics/')) {
          return fetch(request);
        }

        // Map paths: /analytics/* → /api/*
        let rybbitPath = url.pathname.replace('/analytics/', '/api/');

        const rybbitUrl = new URL(rybbitPath, RYBBIT_HOST);
        const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

        const proxyHeaders = new Headers(request.headers);
        proxyHeaders.set('X-Real-IP', clientIp);
        proxyHeaders.set('X-Forwarded-For', clientIp);

        return fetch(rybbitUrl.toString(), {
          method: request.method,
          headers: proxyHeaders,
          body: request.method !== 'GET' ? request.body : undefined,
        });
      }
      ```

      Set environment variable in Cloudflare Dashboard:
      **Workers & Pages** → Your Worker → **Settings** → **Variables** → Add `RYBBIT_HOST`
    </Tab>
  </Tabs>

  ### Deploy Worker [#deploy-worker]

  Click **Save and Deploy** to publish your worker.

  ### Configure Worker Route [#configure-worker-route]

  Set up a route to trigger the worker:

  1. Go to **Workers & Pages** → Your Worker → **Triggers**
  2. Click **Add route**
  3. Configure:
     * **Route**: `yourdomain.com/analytics/*`
     * **Zone**: Select your domain
  4. Click **Save**

  <Callout type="info">
    The route pattern `yourdomain.com/analytics/*` ensures the worker only runs for analytics requests, not your entire site.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Add the script to your website:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Visit your site** with Developer Tools open
  2. **Check Network tab**:
     * Script loads from `/analytics/script.js`
     * Check response headers for `CF-Cache-Status` (HIT/MISS)
  3. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Cloudflare Workers intercept requests at the edge:

1. Request to `yourdomain.com/analytics/script.js` hits Cloudflare edge
2. Worker checks cache for GET requests
3. If not cached, proxies to `app.rybbit.io/api/script.js`
4. Response is cached at the edge location
5. Subsequent requests serve from edge cache (ultra-fast)

All tracking data flows through Cloudflare's network while preserving client IP information.

## Performance Benefits [#performance-benefits]

### Global Edge Network [#global-edge-network]

* **300+ locations worldwide**: Workers run in Cloudflare data centers globally
* **Sub-10ms cold start**: Faster than traditional serverless
* **Automatic scaling**: Handles traffic spikes without configuration

### Built-in Caching [#built-in-caching]

* **Cache API**: Leverages Cloudflare's massive edge cache
* **Intelligent caching**: Scripts cached at edge, tracking requests passed through
* **Instant cache purge**: Clear cache via Cloudflare API if needed

### Zero Infrastructure [#zero-infrastructure]

* **No servers to manage**: Fully serverless
* **Pay-per-request**: Free tier includes 100,000 requests/day
* **Automatic HTTPS**: Cloudflare handles SSL

## Advanced Configuration [#advanced-configuration]

### Cache Control [#cache-control]

Customize caching behavior:

```javascript
// Cache scripts for different durations
if (url.pathname === '/analytics/script.js') {
  cacheResponse.headers.set('Cache-Control', 'public, max-age=3600'); // 1 hour
} else if (url.pathname === '/analytics/replay.js') {
  cacheResponse.headers.set('Cache-Control', 'public, max-age=7200'); // 2 hours
}
```

### Rate Limiting [#rate-limiting]

Add basic rate limiting:

```javascript
// Simple in-memory rate limiting (per edge location)
const rateLimitMap = new Map();

async function checkRateLimit(ip) {
  const key = `ratelimit:${ip}`;
  const current = rateLimitMap.get(key) || { count: 0, resetAt: Date.now() + 60000 };

  if (Date.now() > current.resetAt) {
    current.count = 0;
    current.resetAt = Date.now() + 60000;
  }

  current.count++;
  rateLimitMap.set(key, current);

  return current.count > 100; // 100 requests per minute
}
```

### Logging and Analytics [#logging-and-analytics]

Log proxy usage:

```javascript
async function handleRequest(request) {
  const startTime = Date.now();

  try {
    const response = await proxyToRybbit(request, url);
    const duration = Date.now() - startTime;

    // Log to Cloudflare Analytics Engine (if enabled)
    console.log({
      path: url.pathname,
      status: response.status,
      duration,
      cached: response.headers.get('X-Cache-Status') === 'HIT',
    });

    return response;
  } catch (error) {
    console.error('Proxy error:', error);
    return new Response('Error', { status: 500 });
  }
}
```

## Cost Considerations [#cost-considerations]

Cloudflare Workers pricing (as of 2024):

* **Free tier**: 100,000 requests/day
* **Paid plan**: $5/month for 10 million requests + $0.50 per million after

For typical traffic:

* 100,000 sessions/month ≈ 200,000-500,000 requests (well within free tier)
* Even with session replay: Usually under 1 million requests/month

<Callout type="info">
  Most sites stay within the free tier. Bandwidth is unlimited on all Cloudflare plans.
</Callout>

## Troubleshooting [#troubleshooting]

### Worker not triggering [#worker-not-triggering]

**Problem**: Requests bypass worker.

**Solution**:

1. Verify route is configured: `yourdomain.com/analytics/*`
2. Check zone matches your domain
3. Ensure orange-cloud (proxy) is enabled on DNS record

### Cache not working [#cache-not-working]

**Problem**: `X-Cache-Status` always shows MISS.

**Solution**:

1. Verify cache key includes important parts:
   ```javascript
   const cacheKey = new Request(rybbitUrl, request);
   ```
2. Ensure `Cache-Control` headers are set
3. Check method is GET (POST requests aren't cached)

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show Cloudflare IPs.

**Solution**:
Use `CF-Connecting-IP` header:

```javascript
const clientIp = request.headers.get('CF-Connecting-IP');
proxyHeaders.set('X-Real-IP', clientIp);
```

### Deployment errors [#deployment-errors]

**Problem**: Worker fails to deploy.

**Solution**:

1. Check syntax in editor (no console.log in production)
2. Verify all async functions use await
3. Test locally with Wrangler:
   ```bash
   npm install -g wrangler
   wrangler dev
   ```

## Local Development [#local-development]

Use Wrangler for local testing:

```bash
# Install Wrangler
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Create worker
wrangler init rybbit-proxy

# Dev server
wrangler dev

# Deploy
wrangler deploy
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/) - Official docs
* [Workers Cache API](https://developers.cloudflare.com/workers/runtime-apis/cache/) - Caching documentation


# Express.js Proxy Setup (/fr/docs/proxy-guide/express)





Express.js makes it easy to proxy Rybbit tracking using middleware. This guide shows how to set up a reverse proxy using `http-proxy-middleware`.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

The `http-proxy-middleware` package provides a simple way to proxy requests in Express applications, making it perfect for routing analytics requests to Rybbit servers.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your Express app
* Forward necessary headers for accurate tracking
* Optional caching for better performance
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Node.js and Express.js application
* npm or yarn package manager
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Install http-proxy-middleware [#install-http-proxy-middleware]

  Install the proxy middleware package:

  ```bash
  npm install http-proxy-middleware
  ```

  Or with yarn:

  ```bash
  yarn add http-proxy-middleware
  ```

  ### Configure Environment Variables [#configure-environment-variables]

  Create or update your `.env` file:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  <Callout type="info">
    Install `dotenv` if not already: `npm install dotenv`
  </Callout>

  ### Add Proxy Middleware to Express [#add-proxy-middleware-to-express]

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'TypeScript']">
    <Tab>
      Add to your Express server file (e.g., `server.js` or `app.js`):

      ```javascript
      // server.js
      require('dotenv').config();
      const express = require('express');
      const { createProxyMiddleware } = require('http-proxy-middleware');

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      // Rybbit Analytics Proxy
      // Proxy all /analytics/* requests to Rybbit
      app.use('/analytics', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api', // Rewrite /analytics/script.js to /api/script.js
        },
        onProxyReq: (proxyReq, req, res) => {
          // Forward client IP for accurate geolocation
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
        logLevel: 'warn',
      }));

      // Exception for site config endpoint (different path structure)
      app.use('/analytics/site/tracking-config', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics/site': '/api/site', // Rewrite to /api/site/tracking-config
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
      }));

      // Your other routes
      app.get('/', (req, res) => {
        res.send('Hello World');
      });

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>

    <Tab>
      Minimal setup with basic tracking:

      ```javascript
      // server.js
      require('dotenv').config();
      const express = require('express');
      const { createProxyMiddleware } = require('http-proxy-middleware');

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      // Proxy script and track endpoints only
      app.use(['/analytics/script.js', '/analytics/track'], createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api',
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
      }));

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>

    <Tab>
      For TypeScript projects:

      ```typescript
      // server.ts
      import 'dotenv/config';
      import express, { Request, Response } from 'express';
      import { createProxyMiddleware, Options } from 'http-proxy-middleware';

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      const proxyOptions: Options = {
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api',
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp as string);
          proxyReq.setHeader('X-Real-IP', clientIp as string);
        },
        logLevel: 'warn',
      };

      app.use('/analytics', createProxyMiddleware(proxyOptions));

      app.use('/analytics/site/tracking-config', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics/site': '/api/site',
        },
        onProxyReq: proxyOptions.onProxyReq,
      }));

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>
  </Tabs>

  ### Update Your Tracking Script [#update-your-tracking-script]

  In your HTML or template files:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Start Your Server [#start-your-server]

  ```bash
  node server.js
  ```

  Or with nodemon for development:

  ```bash
  npm install -D nodemon
  npx nodemon server.js
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Test script endpoint**:
     ```bash
     curl -I http://localhost:3000/analytics/script.js
     ```

  2. **Open your app** in a browser with Developer Tools

  3. **Check Network tab**: Requests should go to `/analytics/*`

  4. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

The `http-proxy-middleware` intercepts requests matching the specified paths and forwards them to Rybbit:

1. Request to `/analytics/script.js` is intercepted
2. Path is rewritten to `/api/script.js`
3. Request is forwarded to `https://app.rybbit.io/api/script.js`
4. Client IP headers are added for accurate tracking
5. Response is sent back to the browser

## Advanced Configuration [#advanced-configuration]

### Caching Responses [#caching-responses]

Add caching for better performance:

```javascript
const NodeCache = require('node-cache');
const cache = new NodeCache({ stdTTL: 3600 }); // 1 hour default

// Install: npm install node-cache

// Caching middleware for scripts
const cacheMiddleware = (req, res, next) => {
  const key = req.originalUrl;
  const cachedResponse = cache.get(key);

  if (cachedResponse) {
    res.set('X-Cache-Status', 'HIT');
    return res.send(cachedResponse);
  }

  // Store original send
  const originalSend = res.send.bind(res);
  res.send = (body) => {
    cache.set(key, body);
    res.set('X-Cache-Status', 'MISS');
    return originalSend(body);
  };
  next();
};

// Apply caching only to script files
app.use('/analytics/script.js', cacheMiddleware);
app.use('/analytics/script.js', createProxyMiddleware({
  // ... proxy config
}));
```

### Request Size Limits [#request-size-limits]

For session replay uploads, increase body size limit:

```javascript
const express = require('express');
const app = express();

// Increase limit for session replay endpoints
app.use('/analytics/session-replay', express.json({ limit: '10mb' }));
app.use('/analytics/session-replay', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  pathRewrite: {
    '^/analytics': '/api',
  },
}));
```

### Rate Limiting [#rate-limiting]

Protect your proxy with rate limiting:

```javascript
const rateLimit = require('express-rate-limit');

// Install: npm install express-rate-limit

const analyticsLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 100, // Limit each IP to 100 requests per minute
  message: 'Too many requests from this IP',
  standardHeaders: true,
  legacyHeaders: false,
});

// Apply to tracking endpoints
app.use('/analytics/track', analyticsLimiter);
app.use('/analytics/track', createProxyMiddleware({
  // ... proxy config
}));
```

### Error Handling [#error-handling]

Add error handling for proxy failures:

```javascript
app.use('/analytics', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  pathRewrite: {
    '^/analytics': '/api',
  },
  onError: (err, req, res) => {
    console.error('Proxy error:', err);
    res.status(500).json({ error: 'Analytics proxy error' });
  },
  onProxyReq: (proxyReq, req, res) => {
    const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
    proxyReq.setHeader('X-Forwarded-For', clientIp);
    proxyReq.setHeader('X-Real-IP', clientIp);
  },
}));
```

### CORS Configuration [#cors-configuration]

If serving API endpoints to other domains:

```javascript
const cors = require('cors');

// Install: npm install cors

app.use('/analytics', cors({
  origin: ['https://yourdomain.com', 'https://www.yourdomain.com'],
  credentials: true,
}));

app.use('/analytics', createProxyMiddleware({
  // ... proxy config
}));
```

## Troubleshooting [#troubleshooting]

### Requests timing out [#requests-timing-out]

**Problem**: Proxy requests hang or timeout.

**Solution**:
Increase timeout limits:

```javascript
app.use('/analytics', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  timeout: 30000, // 30 seconds
  proxyTimeout: 30000,
  pathRewrite: {
    '^/analytics': '/api',
  },
}));
```

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show server's location.

**Solution**:
Ensure IP forwarding is configured:

```javascript
onProxyReq: (proxyReq, req, res) => {
  const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  proxyReq.setHeader('X-Forwarded-For', clientIp);
  proxyReq.setHeader('X-Real-IP', clientIp);
}
```

### Path rewriting issues [#path-rewriting-issues]

**Problem**: 404 errors on Rybbit endpoints.

**Solution**:
Check path rewriting is correct:

```javascript
pathRewrite: {
  '^/analytics': '/api', // /analytics/script.js → /api/script.js
}
```

Debug by logging:

```javascript
onProxyReq: (proxyReq, req, res) => {
  console.log('Proxying:', req.method, req.path, '→', proxyReq.path);
}
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [http-proxy-middleware docs](https://github.com/chimurai/http-proxy-middleware) - Middleware documentation


# Generic Proxy Setup (/fr/docs/proxy-guide/get-started)





This guide covers the core concepts for setting up a Rybbit proxy with any reverse proxy or server framework. If your specific framework has a dedicated guide, we recommend following that instead for optimized instructions.

## Prerequisites [#prerequisites]

Before setting up the proxy, ensure you have:

* **A domain or subdomain** where you'll serve the proxied scripts (e.g., `yourdomain.com` or `analytics.yourdomain.com`)
* **SSL/TLS certificate** for HTTPS (required for modern browsers)
* **Server or platform** with reverse proxy capabilities
* **Your Rybbit instance URL**:
  * Cloud: `https://app.rybbit.io`
  * Self-hosted: Your Rybbit instance URL (e.g., `https://analytics.yourcompany.com`)
* **Your Rybbit site ID** (found in your Rybbit dashboard)

## Understanding the Endpoints [#understanding-the-endpoints]

Rybbit uses several endpoints for tracking. You can choose between a minimal setup or full proxy:

<Tabs items="['Minimal Setup', 'Full Setup (Recommended)']">
  <Tab>
    **Required endpoints for basic tracking:**

    | Endpoint         | Method | Purpose                 | Cache    |
    | ---------------- | ------ | ----------------------- | -------- |
    | `/api/script.js` | GET    | Main tracking script    | 1 hour   |
    | `/api/track`     | POST   | Event tracking endpoint | No cache |

    This minimal setup enables basic pageview and event tracking, but won't support session replay or some advanced features.
  </Tab>

  <Tab>
    **All endpoints for complete functionality:**

    | Endpoint                             | Method | Purpose                         | Cache     |
    | ------------------------------------ | ------ | ------------------------------- | --------- |
    | `/api/script.js`                     | GET    | Main tracking script (minified) | 1 hour    |
    | `/api/replay.js`                     | GET    | Session replay recording script | 1 day     |
    | `/api/metrics.js`                    | GET    | Web Vitals metrics script       | 1 day     |
    | `/api/track`                         | POST   | Event tracking endpoint         | No cache  |
    | `/api/identify`                      | POST   | User identification endpoint    | No cache  |
    | `/api/session-replay/record/:siteId` | POST   | Session replay data upload      | No cache  |
    | `/api/site/tracking-config/:siteId`  | GET    | Site configuration              | 5 minutes |

    This setup supports all Rybbit features including session replay, Web Vitals, and custom events.
  </Tab>
</Tabs>

<Callout type="info">
  The session replay and metrics scripts (`/api/replay.js` and `/api/metrics.js`) are loaded dynamically by the main script when those features are enabled in your site settings. You don't need to include them in your HTML.
</Callout>

## Implementation Steps [#implementation-steps]

<Steps>
  ### Configure Your Proxy Rules [#configure-your-proxy-rules]

  Set up your reverse proxy to forward requests from your chosen path (e.g., `/analytics/*`) to the Rybbit server.

  **Generic proxy configuration pattern:**

  ```
  Your domain path          →  Rybbit backend
  -----------------            ---------------
  /analytics/script.js      →  https://app.rybbit.io/api/script.js
  /analytics/track          →  https://app.rybbit.io/api/track
  /analytics/replay.js      →  https://app.rybbit.io/api/replay.js
  ... and so on
  ```

  **Key requirements:**

  * Preserve the HTTP method (GET or POST)
  * Forward the browser's original request headers — pass through **all** incoming headers except `Host` and hop-by-hop headers (`Connection`, `Content-Length`), rather than hand-picking a few. See [Request Header Forwarding](#request-header-forwarding) for why this matters.
  * Maintain request/response body for POST requests
  * Set appropriate Content-Type headers
  * Forward the visitor IP in `X-Forwarded-For`
  * Enable the **First-Party Proxy** toggle for your site (see below)

  ### Enable First-Party Proxy in Site Settings [#enable-first-party-proxy-in-site-settings]

  In your Rybbit dashboard, open **Site Settings → Privacy & Security** and enable **First-Party Proxy**. This tells Rybbit that requests for this site arrive via your proxy, so the visitor IP in `X-Forwarded-For` is trusted directly instead of being inferred from network topology. Without it, Rybbit may attribute traffic to your proxy server's IP — producing wrong geolocation and merging all visitors into a few users.

  ### Configure Caching (Optional but Recommended) [#configure-caching-optional-but-recommended]

  Implement caching to reduce load on Rybbit servers and improve performance:

  **Recommended cache durations:**

  * **Scripts** (`.js` files): 1 hour (3600 seconds)
    * These change infrequently but may be updated for bug fixes
  * **Site configuration** (`/api/site/tracking-config/*`): 5 minutes (300 seconds)
    * Updated when you change settings in the dashboard
  * **Tracking endpoints** (POST requests): Never cache
    * Each request contains unique event data

  **Example cache headers to set:**

  ```
  Cache-Control: public, max-age=3600  # For scripts
  Cache-Control: public, max-age=300   # For config
  Cache-Control: no-store              # For tracking POSTs
  ```

  ### Update Your Tracking Script [#update-your-tracking-script]

  Change your script tag to load from your proxied domain instead of directly from Rybbit:

  **Before (direct loading):**

  ```html
  <script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  **After (proxied):**

  ```html
  <script src="https://yourdomain.com/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  <Callout type="info">
    **How Auto-Discovery Works**: The Rybbit script automatically extracts the analytics host from its own `src` attribute by splitting on `/script.js`. This means when it loads from `https://yourdomain.com/analytics/script.js`, it automatically sends all tracking data to `https://yourdomain.com/analytics/*` endpoints.
  </Callout>

  ### Verify the Setup [#verify-the-setup]

  Test your proxy configuration to ensure everything works correctly:

  1. **Open your website** in a browser with Developer Tools open
  2. **Go to the Network tab** and filter by "script" or your proxy path
  3. **Verify the script loads**:
     * You should see a request to `yourdomain.com/analytics/script.js`
     * Status should be `200 OK`
     * Content-Type should be `application/javascript`
  4. **Verify tracking works**:
     * Navigate to another page or trigger an event
     * You should see POST requests to `yourdomain.com/analytics/track`
     * Check the response is successful (200 OK)
  5. **Check your Rybbit dashboard**:
     * Wait 1-2 minutes for data to process
     * Verify your session appears in real-time dashboard

  ### Configure Security Headers (Optional) [#configure-security-headers-optional]

  Add security headers to protect your proxy:

  **Recommended headers:**

  ```
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  Referrer-Policy: strict-origin-when-cross-origin
  ```

  **CORS headers** (should be preserved from Rybbit):

  ```
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, OPTIONS
  Access-Control-Allow-Headers: Content-Type
  ```
</Steps>

## Request Header Forwarding [#request-header-forwarding]

Forward the browser's original headers to the Rybbit backend. The simplest and most robust approach is to pass through **every** incoming request header except `Host` and hop-by-hop headers (`Connection`, `Content-Length` — let your HTTP client recompute those).

Why this matters: Rybbit's bot detection scores requests on headers that every real browser sends. A proxy that forwards only `User-Agent` and the visitor IP produces requests that look exactly like a script — the events return `200 OK` but are classified as bot traffic and never appear in your dashboard.

If you must whitelist headers instead of passing everything through, this is the minimum set:

| Header                                                | Purpose                                            | Required    |
| ----------------------------------------------------- | -------------------------------------------------- | ----------- |
| `User-Agent`                                          | Device and browser detection                       | Yes         |
| `X-Forwarded-For`                                     | Visitor IP for geolocation and user identification | Yes         |
| `Accept-Language`                                     | Language detection, bot filtering                  | Yes         |
| `Accept`                                              | Bot filtering                                      | Yes         |
| `Accept-Encoding`                                     | Bot filtering (must include `gzip`)                | Yes         |
| `Sec-Fetch-Site`, `Sec-Fetch-Mode`, `Sec-Fetch-Dest`  | Bot filtering (sent by all Chromium browsers)      | Yes         |
| `Sec-CH-UA`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Platform` | Browser detection                                  | Recommended |
| `Referer`                                             | Referrer tracking                                  | Recommended |
| `Content-Type`                                        | POST body parsing                                  | Yes (POSTs) |

<Callout type="warn">
  **IP Forwarding**: Rybbit uses IP addresses for geolocation (country/city) and creating anonymous user identifiers (hashed IP + User Agent). If you don't forward the visitor IP in `X-Forwarded-For`, all traffic will appear to come from your proxy server's IP.
</Callout>

### Forwarded IP Headers [#forwarded-ip-headers]

Set `X-Forwarded-For` to the original visitor IP before forwarding the request to Rybbit, and enable the **First-Party Proxy** toggle in your site settings so Rybbit trusts it unconditionally.

<Callout type="warn">
  **Use `X-Forwarded-For`, not `X-Real-IP`.** On Rybbit Cloud, `X-Real-IP` is consumed by our edge network (Cloudflare treats it as an internal header) and never reaches the backend — a proxy that relies on it will silently fall back to the wrong IP. `X-Forwarded-For` passes through intact. Coincidentally, AWS CloudFront also cannot send `X-Real-IP` (it's on the [origin custom-header denylist](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html#add-origin-custom-headers-denylist)). Setting `X-Real-IP` as well does no harm on self-hosted instances, but never make it the only IP header.
</Callout>

**Cloudflare Worker example:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

const proxyHeaders = new Headers(request.headers);
proxyHeaders.set('X-Real-IP', clientIp);
proxyHeaders.set('X-Forwarded-For', clientIp);
```

**CloudFront example:**

* Set `X-Forwarded-For` to the viewer IP from a CloudFront Function/Lambda\@Edge (CloudFront cannot forward `X-Real-IP`)
* Forward `User-Agent`, `Referer`, and `Accept-Language`

```javascript
// CloudFront Function (viewer-request)
function handler(event) {
  event.request.headers["x-forwarded-for"] = { value: event.viewer.ip };
  return event.request;
}
```

## Bandwidth Considerations [#bandwidth-considerations]

Proxying adds bandwidth usage to your infrastructure. Here's what to expect:

**Typical bandwidth per session:**

* Initial script load: \~18 KB (one-time per session)
* Pageview tracking: \~0.5-2 KB per pageview
* Custom events: \~0.5-3 KB per event
* Session replay: 50-500 KB per session (if enabled, varies by session length)
* Web Vitals: \~1-2 KB per page

**Estimated monthly bandwidth** for a site with 100,000 monthly sessions:

* Without session replay: \~5-10 GB/month
* With session replay: \~30-80 GB/month

Most modern hosting plans can handle this easily, but verify your bandwidth limits if you have high traffic or session replay enabled.

## Performance Optimization [#performance-optimization]

### Use a CDN [#use-a-cdn]

If your server has CDN capabilities (like Cloudflare, Fastly, or AWS CloudFront), configure it to cache the static scripts:

* Cache scripts at edge locations worldwide
* Reduce latency for global users
* Offload bandwidth from your origin server

### Enable Compression [#enable-compression]

Ensure your proxy enables gzip or brotli compression:

```
Content-Encoding: gzip
```

This can reduce script size by 60-70%, improving load times and reducing bandwidth.

### Connection Reuse [#connection-reuse]

Configure your proxy to maintain persistent connections to Rybbit's backend to reduce latency on repeated requests.

## Common Proxy Patterns [#common-proxy-patterns]

<Tabs items="['Subdomain Proxy', 'Path-Based Proxy']">
  <Tab>
    Use a dedicated subdomain for analytics:

    ```
    https://analytics.yourdomain.com/script.js  →  https://app.rybbit.io/api/script.js
    https://analytics.yourdomain.com/track      →  https://app.rybbit.io/api/track
    ```

    **Pros:**

    * Clean separation of concerns
    * Easy to manage SSL certificate
    * Can use separate CDN configuration

    **Cons:**

    * Additional DNS lookup (minor performance impact)
    * Need to manage subdomain DNS
  </Tab>

  <Tab>
    Use a path on your main domain:

    ```
    https://yourdomain.com/analytics/script.js  →  https://app.rybbit.io/api/script.js
    https://yourdomain.com/analytics/track      →  https://app.rybbit.io/api/track
    ```

    **Pros:**

    * No additional DNS lookup
    * Single SSL certificate
    * Truly first-party from browser perspective

    **Cons:**

    * Must ensure proxy path doesn't conflict with your app routes
  </Tab>
</Tabs>

## Security Considerations [#security-considerations]

### Rate Limiting [#rate-limiting]

Consider adding rate limiting to prevent abuse:

* Limit POST requests to tracking endpoints (e.g., 100 requests per minute per IP)
* Whitelist your Rybbit backend IP if possible
* Monitor for unusual traffic patterns

### Request Size Limits [#request-size-limits]

Set appropriate request body size limits:

* `/api/track`, `/api/identify`: 1 MB max
* `/api/session-replay/record/*`: 10 MB max (session replay can send large payloads)

### HTTPS Only [#https-only]

Always serve your proxy over HTTPS:

* Modern browsers require HTTPS for many features
* Protects user data in transit
* Required for accurate tracking in secure contexts

## Troubleshooting [#troubleshooting]

If something isn't working, check:

1. **Script loads but no events tracked**: Verify all tracking endpoints (`/api/track`, etc.) are proxied
2. **CORS errors**: Ensure CORS headers are preserved from Rybbit backend
3. **404 errors**: Check that URL paths exactly match expected format
4. **Incorrect geolocation**: Verify `X-Forwarded-For` is set to the visitor IP and the **First-Party Proxy** toggle is enabled in site settings
5. **`/track` returns 200 but nothing appears in the dashboard**: Your proxy is probably forwarding too few headers and events are being classified as bot traffic — forward the full browser header set (see [Request Header Forwarding](#request-header-forwarding))
6. **Session replay not working**: Add `/api/replay.js` and `/api/session-replay/record/:siteId` endpoints

For more detailed troubleshooting, see our [troubleshooting guide](/docs/proxy-guide/troubleshooting).

## Next Steps [#next-steps]

Now that you understand the generic concepts, choose your specific framework or platform for detailed implementation instructions:

* [Next.js](/docs/proxy-guide/next-js)
* [Nginx](/docs/proxy-guide/nginx)
* [Caddy](/docs/proxy-guide/caddy)
* [Vercel](/docs/proxy-guide/vercel)
* [Express.js](/docs/proxy-guide/express)
* [Laravel](/docs/proxy-guide/laravel)
* [Astro](/docs/proxy-guide/astro)
* [Cloudflare Workers](/docs/proxy-guide/cloudflare-workers)


# Proxy Setup Guide (/fr/docs/proxy-guide)





Proxying Rybbit's tracking script through your own domain helps bypass ad blockers and improves tracking accuracy by making all analytics requests appear as first-party traffic.

## What is Proxy Setup? [#what-is-proxy-setup]

When you add Rybbit's tracking script directly to your website using the default installation:

```html
<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
```

The browser loads the script from `app.rybbit.io`, which ad blockers can identify and block as third-party analytics. Even though Rybbit is privacy-focused and doesn't use cookies, some ad blockers use aggressive blocking rules that target any analytics domains.

**Proxying solves this** by serving the tracking script and handling tracking requests through your own domain (e.g., `yourdomain.com/analytics/script.js`), making all tracking appear as first-party traffic.

<Callout type="info">
  Rybbit is fully compliant with GDPR, CCPA, and other privacy regulations. It uses cookieless tracking based on IP + User Agent hashing with optional daily rotating salts. Proxying is about improving data accuracy, not circumventing privacy laws.
</Callout>

## Why Proxy Rybbit? [#why-proxy-rybbit]

### Improve Tracking Accuracy [#improve-tracking-accuracy]

Ad blockers are becoming increasingly aggressive and may block analytics scripts regardless of their privacy practices. By proxying through your own domain:

* **Bypass ad blocker detection**: Requests appear as first-party traffic to your own domain
* **Increase data completeness**: Typical improvement of 10-30% in tracked sessions
* **Maintain accurate metrics**: Get a true picture of your website's performance

### Stay Privacy-Compliant [#stay-privacy-compliant]

Proxying doesn't compromise user privacy:

* No cookies are used (Rybbit remains cookieless)
* User data is still processed according to your privacy policy
* GDPR, CCPA, and other privacy regulations remain fully satisfied
* Users can still opt out through browser settings or Do Not Track

### Better Performance (Optional) [#better-performance-optional]

With proper caching configuration, proxying can also improve performance:

* Serve scripts from your CDN or edge network
* Reduce DNS lookups (one less domain to resolve)
* Cache static scripts closer to your users

## How It Works [#how-it-works]

Here's the flow when you proxy Rybbit:

1. **User visits your website**: Your HTML includes the tracking script from your domain
   ```html
   <script src="https://yourdomain.com/analytics/script.js" data-site-id="123"></script>
   ```

2. **Script loads from your domain**: Your server proxies the request to Rybbit's servers
   * Request: `yourdomain.com/analytics/script.js` → proxied to → `app.rybbit.io/api/script.js`

3. **Script auto-discovers analytics host**: The Rybbit script automatically detects the domain it was loaded from
   ```typescript
   // The script extracts the host from its own src attribute
   const analyticsHost = src.split("/script.js")[0];
   // Result: "https://yourdomain.com/analytics"
   ```

4. **Tracking data sent through your domain**: All analytics events are sent to your domain and proxied to Rybbit
   * Event tracking: `yourdomain.com/analytics/track` → proxied to → `app.rybbit.io/api/track`
   * Session replay: `yourdomain.com/analytics/session-replay/record/{siteId}` → proxied
   * Configuration: `yourdomain.com/analytics/site/tracking-config/{siteId}` → proxied

5. **Data appears in your Rybbit dashboard**: No changes needed in the Rybbit interface

<Callout type="warn">
  **Bandwidth Consideration**: All tracking requests will flow through your server infrastructure, which will increase bandwidth usage. For most sites this is minimal (typically 10-50KB per session), but consider this when evaluating hosting costs.
</Callout>

## Choose Your Framework [#choose-your-framework]

Select the framework or platform that matches your setup:

<Cards>
  <Card icon="<SiNextdotjs />" title="Next.js" href="/docs/proxy-guide/next-js" className="flex items-center gap-2" />

  <Card icon="<SiNginx />" title="Nginx" href="/docs/proxy-guide/nginx" className="flex items-center gap-2" />

  <Card title="Caddy" href="/docs/proxy-guide/caddy" className="flex items-center gap-2" />

  <Card icon="<SiVercel />" title="Vercel" href="/docs/proxy-guide/vercel" className="flex items-center gap-2" />

  <Card icon="<SiExpress />" title="Express.js" href="/docs/proxy-guide/express" className="flex items-center gap-2" />

  <Card icon="<SiLaravel />" title="Laravel" href="/docs/proxy-guide/laravel" className="flex items-center gap-2" />

  <Card icon="<SiAstro />" title="Astro" href="/docs/proxy-guide/astro" className="flex items-center gap-2" />

  <Card icon="<SiCloudflare />" title="Cloudflare Workers" href="/docs/proxy-guide/cloudflare-workers" className="flex items-center gap-2" />
</Cards>

## Generic Implementation [#generic-implementation]

If your framework isn't listed above, check out our [generic implementation guide](/docs/proxy-guide/get-started) that covers the core concepts applicable to any reverse proxy or server setup.

## Need Help? [#need-help]

If you encounter issues during setup, check our [troubleshooting guide](/docs/proxy-guide/troubleshooting) for common problems and solutions.


# Laravel Proxy Setup (/fr/docs/proxy-guide/laravel)





Laravel makes it straightforward to proxy Rybbit tracking using routes and the HTTP client. This guide shows how to set up proxy endpoints in your Laravel application.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Laravel's HTTP client (built on Guzzle) provides an elegant way to proxy requests to Rybbit servers while maintaining full control over headers, caching, and error handling.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your Laravel app
* Forward necessary headers for accurate tracking
* Optional caching with Laravel Cache
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Laravel 8 or later
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Configure Environment Variables [#configure-environment-variables]

  Add your Rybbit host to `.env`:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  ### Create Analytics Controller [#create-analytics-controller]

  Generate a controller for handling analytics proxying:

  ```bash
  php artisan make:controller AnalyticsProxyController
  ```

  Then implement the proxy logic:

  ```php
  <?php
  // app/Http/Controllers/AnalyticsProxyController.php

  namespace App\Http\Controllers;

  use Illuminate\Http\Request;
  use Illuminate\Support\Facades\Http;
  use Illuminate\Support\Facades\Cache;

  class AnalyticsProxyController extends Controller
  {
      private string $rybbitHost;

      public function __construct()
      {
          $this->rybbitHost = config('services.rybbit.host', 'https://app.rybbit.io');
      }

      /**
       * Proxy script requests (GET)
       */
      public function proxyScript(Request $request, string $script)
      {
          // Cache scripts for 1 hour
          $cacheKey = "rybbit_script_{$script}";

          return Cache::remember($cacheKey, 3600, function () use ($script, $request) {
              return $this->forwardRequest("api/{$script}", 'GET', $request);
          });
      }

      /**
       * Proxy tracking requests (POST)
       */
      public function proxyTrack(Request $request)
      {
          return $this->forwardRequest('api/track', 'POST', $request);
      }

      /**
       * Proxy identify requests (POST)
       */
      public function proxyIdentify(Request $request)
      {
          return $this->forwardRequest('api/identify', 'POST', $request);
      }

      /**
       * Proxy session replay recording (POST)
       */
      public function proxySessionReplay(Request $request, string $siteId)
      {
          return $this->forwardRequest("api/session-replay/record/{$siteId}", 'POST', $request);
      }

      /**
       * Proxy site configuration (GET)
       */
      public function proxySiteConfig(Request $request, string $siteId)
      {
          // Cache config for 5 minutes
          $cacheKey = "rybbit_config_{$siteId}";

          return Cache::remember($cacheKey, 300, function () use ($siteId, $request) {
              return $this->forwardRequest("api/site/tracking-config/{$siteId}", 'GET', $request);
          });
      }

      /**
       * Forward request to Rybbit backend
       */
      private function forwardRequest(string $path, string $method, Request $request)
      {
          $url = "{$this->rybbitHost}/{$path}";

          // Get client IP
          $clientIp = $request->header('X-Forwarded-For', $request->ip());

          // Build HTTP request
          $httpRequest = Http::timeout(30)
              ->withHeaders([
                  'X-Real-IP' => $clientIp,
                  'X-Forwarded-For' => $clientIp,
                  'User-Agent' => $request->header('User-Agent'),
                  'Referer' => $request->header('Referer', ''),
              ]);

          try {
              if ($method === 'POST') {
                  $response = $httpRequest->post($url, $request->all());
              } else {
                  $response = $httpRequest->get($url);
              }

              return response($response->body(), $response->status())
                  ->header('Content-Type', $response->header('Content-Type'));
          } catch (\Exception $e) {
              \Log::error('Rybbit proxy error', [
                  'url' => $url,
                  'error' => $e->getMessage(),
              ]);

              return response()->json(['error' => 'Analytics proxy error'], 500);
          }
      }
  }
  ```

  ### Add Routes [#add-routes]

  Add routes for the analytics proxy in `routes/web.php`:

  ```php
  <?php
  // routes/web.php

  use App\Http\Controllers\AnalyticsProxyController;

  // Analytics proxy routes
  Route::prefix('analytics')->group(function () {
      // Scripts (GET)
      Route::get('/{script}', [AnalyticsProxyController::class, 'proxyScript'])
          ->where('script', '(script|replay|metrics)\.js');

      // Tracking endpoints (POST)
      Route::post('/track', [AnalyticsProxyController::class, 'proxyTrack']);
      Route::post('/identify', [AnalyticsProxyController::class, 'proxyIdentify']);
      Route::post('/session-replay/record/{siteId}', [AnalyticsProxyController::class, 'proxySessionReplay']);

      // Configuration (GET)
      Route::get('/site/tracking-config/{siteId}', [AnalyticsProxyController::class, 'proxySiteConfig']);
  });
  ```

  ### Add Service Configuration (Optional) [#add-service-configuration-optional]

  Add Rybbit configuration to `config/services.php`:

  ```php
  <?php
  // config/services.php

  return [
      // ... other services

      'rybbit' => [
          'host' => env('RYBBIT_HOST', 'https://app.rybbit.io'),
      ],
  ];
  ```

  ### Update Your Blade Templates [#update-your-blade-templates]

  Add the tracking script to your layout:

  ```blade
  {{-- resources/views/layouts/app.blade.php --}}
  <!DOCTYPE html>
  <html lang="en">
  <head>
      <meta charset="UTF-8">
      <title>{{ config('app.name') }}</title>

      {{-- Rybbit Analytics --}}
      <script src="{{ url('/analytics/script.js') }}" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      @yield('content')
  </body>
  </html>
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Clear route cache** (if caching enabled):
     ```bash
     php artisan route:clear
     ```

  2. **Visit your application** with Developer Tools open

  3. **Check Network tab**: Requests should go to `/analytics/*`

  4. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Laravel routes intercept requests to `/analytics/*` and forward them to Rybbit:

1. Request to `/analytics/script.js` hits Laravel route
2. Controller forwards to `https://app.rybbit.io/api/script.js`
3. Response is cached (for cacheable endpoints)
4. Client IP and headers are preserved for accurate tracking

## Advanced Configuration [#advanced-configuration]

### Middleware for Rate Limiting [#middleware-for-rate-limiting]

Create rate limiting middleware:

```bash
php artisan make:middleware RateLimitAnalytics
```

```php
<?php
// app/Http/Middleware/RateLimitAnalytics.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Cache\RateLimiter;

class RateLimitAnalytics
{
    protected $limiter;

    public function __construct(RateLimiter $limiter)
    {
        $this->limiter = $limiter;
    }

    public function handle($request, Closure $next)
    {
        $key = 'analytics:' . $request->ip();

        if ($this->limiter->tooManyAttempts($key, 100)) {
            return response('Too Many Requests', 429);
        }

        $this->limiter->hit($key, 60); // 100 requests per minute

        return $next($request);
    }
}
```

Register in `app/Http/Kernel.php`:

```php
protected $routeMiddleware = [
    // ... other middleware
    'rate.limit.analytics' => \App\Http\Middleware\RateLimitAnalytics::class,
];
```

Apply to routes:

```php
Route::prefix('analytics')->middleware('rate.limit.analytics')->group(function () {
    // ... routes
});
```

### Custom Cache Configuration [#custom-cache-configuration]

Use different cache drivers for analytics:

```php
private function forwardRequest(string $path, string $method, Request $request)
{
    // Use Redis for analytics caching
    $cache = Cache::store('redis');

    // Or use file cache
    // $cache = Cache::store('file');

    // ... rest of the method
}
```

### Queue Large Requests [#queue-large-requests]

For large session replay uploads, use queues:

```bash
php artisan make:job ForwardAnalyticsData
```

```php
<?php
// app/Jobs/ForwardAnalyticsData.php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Http;

class ForwardAnalyticsData implements ShouldQueue
{
    use Queueable;

    protected $url;
    protected $data;
    protected $headers;

    public function __construct(string $url, array $data, array $headers)
    {
        $this->url = $url;
        $this->data = $data;
        $this->headers = $headers;
    }

    public function handle()
    {
        Http::withHeaders($this->headers)
            ->post($this->url, $this->data);
    }
}
```

Use in controller for session replay:

```php
public function proxySessionReplay(Request $request, string $siteId)
{
    // Dispatch job for async processing
    ForwardAnalyticsData::dispatch(
        "{$this->rybbitHost}/api/session-replay/record/{$siteId}",
        $request->all(),
        [
            'X-Real-IP' => $request->ip(),
            'User-Agent' => $request->header('User-Agent'),
        ]
    );

    return response()->json(['status' => 'queued']);
}
```

### CORS Configuration [#cors-configuration]

If serving from a different domain:

```php
<?php
// config/cors.php

return [
    'paths' => ['analytics/*'],
    'allowed_methods' => ['GET', 'POST'],
    'allowed_origins' => ['https://yourdomain.com'],
    'allowed_headers' => ['Content-Type', 'X-Requested-With'],
];
```

## Troubleshooting [#troubleshooting]

### 404 Not Found [#404-not-found]

**Problem**: Routes return 404.

**Solution**:

1. Clear route cache: `php artisan route:clear`
2. List routes to verify: `php artisan route:list --path=analytics`
3. Check route order (more specific routes first)

### Session errors with POST requests [#session-errors-with-post-requests]

**Problem**: CSRF token errors on tracking endpoints.

**Solution**:
Exclude analytics routes from CSRF protection in `app/Http/Middleware/VerifyCsrfToken.php`:

```php
protected $except = [
    'analytics/*',
];
```

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show server's location.

**Solution**:
Ensure IP forwarding in controller:

```php
$clientIp = $request->header('X-Forwarded-For', $request->ip());
```

And add to HTTP request:

```php
'X-Real-IP' => $clientIp,
'X-Forwarded-For' => $clientIp,
```

### Cache not clearing [#cache-not-clearing]

**Problem**: Old script cached after Rybbit update.

**Solution**:
Clear specific cache key:

```bash
php artisan cache:forget rybbit_script_script.js
```

Or clear all cache:

```bash
php artisan cache:clear
```

## Performance Optimization [#performance-optimization]

### Cache Optimization [#cache-optimization]

```php
// Configure cache tags for easy clearing
Cache::tags(['rybbit', 'scripts'])->remember($cacheKey, 3600, function () {
    // ... fetch script
});

// Clear all Rybbit cache
Cache::tags(['rybbit'])->flush();
```

### HTTP Client Optimization [#http-client-optimization]

```php
// Use connection pooling
Http::pool(fn (Pool $pool) => [
    $pool->get("{$this->rybbitHost}/api/script.js"),
    $pool->get("{$this->rybbitHost}/api/replay.js"),
]);
```

## Related Resources [#related-resources]

* [Laravel Integration Guide](/docs/guides/laravel) - General Laravel integration
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Laravel HTTP Client](https://laravel.com/docs/http-client) - Official Laravel docs


# Next.js Proxy Setup (/fr/docs/proxy-guide/next-js)





Next.js provides a powerful [rewrites](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) feature that makes it easy to proxy Rybbit tracking through your own domain. This guide works with both the App Router (Next.js 13+) and Pages Router.

<Callout type="info">
  Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**. Rewrites on this platform automatically forward the browser's headers and set `X-Forwarded-For` to the visitor IP — the toggle tells Rybbit to trust that forwarded IP directly.
</Callout>

## Overview [#overview]

Next.js rewrites allow you to map incoming request paths to different destination URLs transparently. This is perfect for proxying analytics since the browser sees requests to your domain while Next.js forwards them to Rybbit's servers behind the scenes.

**What you'll achieve:**

* Serve Rybbit scripts from your domain (e.g., `/analytics/script.js`)
* Proxy all tracking requests through your Next.js application
* Bypass ad blocker detection with first-party requests
* Support all Rybbit features (session replay, Web Vitals, custom events)

## Prerequisites [#prerequisites]

* Next.js 12 or later (rewrites are supported in all modern versions)
* Your Rybbit site ID (found in your dashboard)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL (e.g., `https://analytics.yourcompany.com`)

## Implementation [#implementation]

<Steps>
  ### Configure Environment Variables [#configure-environment-variables]

  Create or update your `.env` or `.env.local` file with your Rybbit instance URL:

  <Tabs items="['Cloud Hosted', 'Self-Hosted']">
    <Tab>
      ```bash
      # .env.local
      NEXT_PUBLIC_RYBBIT_HOST=https://app.rybbit.io
      ```
    </Tab>

    <Tab>
      ```bash
      # .env.local
      NEXT_PUBLIC_RYBBIT_HOST=https://analytics.yourcompany.com
      ```

      Replace `analytics.yourcompany.com` with your actual Rybbit instance domain.
    </Tab>
  </Tabs>

  <Callout type="info">
    The `NEXT_PUBLIC_` prefix makes this environment variable available in both server and client environments, though it's primarily used during build time for the rewrites configuration.
  </Callout>

  ### Set Up Rewrites in next.config.js [#set-up-rewrites-in-nextconfigjs]

  Add or update the `rewrites` function in your `next.config.js` (or `next.config.mjs` for ESM):

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'ESM (next.config.mjs)']">
    <Tab>
      This configuration proxies all Rybbit endpoints including session replay and Web Vitals:

      ```javascript
      // next.config.js
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            // Tracking scripts
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/replay.js',
              destination: `${rybbitHost}/api/replay.js`,
            },
            {
              source: '/analytics/metrics.js',
              destination: `${rybbitHost}/api/metrics.js`,
            },
            // Tracking endpoints
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
            {
              source: '/analytics/identify',
              destination: `${rybbitHost}/api/identify`,
            },
            {
              source: '/analytics/session-replay/record/:siteId',
              destination: `${rybbitHost}/api/session-replay/record/:siteId`,
            },
            {
              source: '/analytics/site/tracking-config/:siteId',
              destination: `${rybbitHost}/api/site/tracking-config/:siteId`,
            },
          ];
        },
      };

      module.exports = nextConfig;
      ```
    </Tab>

    <Tab>
      Minimal setup with just script loading and basic event tracking:

      ```javascript
      // next.config.js
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
          ];
        },
      };

      module.exports = nextConfig;
      ```

      <Callout type="warn">
        This minimal setup won't support session replay or Web Vitals. Use the full proxy configuration if you need these features.
      </Callout>
    </Tab>

    <Tab>
      If you're using ES modules:

      ```javascript
      // next.config.mjs
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
            {
              source: '/analytics/replay.js',
              destination: `${rybbitHost}/api/replay.js`,
            },
            {
              source: '/analytics/metrics.js',
              destination: `${rybbitHost}/api/metrics.js`,
            },
            {
              source: '/analytics/identify',
              destination: `${rybbitHost}/api/identify`,
            },
            {
              source: '/analytics/session-replay/record/:siteId',
              destination: `${rybbitHost}/api/session-replay/record/:siteId`,
            },
            {
              source: '/analytics/site/tracking-config/:siteId',
              destination: `${rybbitHost}/api/site/tracking-config/:siteId`,
            },
          ];
        },
      };

      export default nextConfig;
      ```
    </Tab>
  </Tabs>

  <Callout type="info">
    **Custom Path**: You can change `/analytics` to any path you prefer (e.g., `/tracking`, `/stats`, `/rybbit`). Just ensure you use the same path consistently in both your rewrites and script tag.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your script tag to load from the proxied path instead of directly from Rybbit:

  <Tabs items="['App Router (Next.js 13+)', 'Pages Router', 'JavaScript (No TypeScript)']">
    <Tab>
      Update your root layout file:

      ```tsx
      // app/layout.tsx
      import Script from 'next/script';

      export default function RootLayout({
        children,
      }: {
        children: React.ReactNode;
      }) {
        return (
          <html lang="en">
            <body>
              {children}
              <Script
                src="/analytics/script.js"
                data-site-id="YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </body>
          </html>
        );
      }
      ```

      Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.
    </Tab>

    <Tab>
      Update your `_app.tsx` or `_app.jsx` file:

      ```tsx
      // pages/_app.tsx
      import Script from 'next/script';
      import type { AppProps } from 'next/app';

      function MyApp({ Component, pageProps }: AppProps) {
        return (
          <>
            <Component {...pageProps} />
            <Script
              src="/analytics/script.js"
              data-site-id="YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </>
        );
      }

      export default MyApp;
      ```

      Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.
    </Tab>

    <Tab>
      ```jsx
      // app/layout.js or pages/_app.js
      import Script from 'next/script';

      export default function RootLayout({ children }) {
        return (
          <html lang="en">
            <body>
              {children}
              <Script
                src="/analytics/script.js"
                data-site-id="YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </body>
          </html>
        );
      }
      ```
    </Tab>
  </Tabs>

  ### Restart Your Development Server [#restart-your-development-server]

  After updating `next.config.js`, restart your Next.js development server for the changes to take effect:

  ```bash
  # Stop the server (Ctrl+C) and restart
  npm run dev
  # or
  yarn dev
  # or
  pnpm dev
  ```

  ### Verify the Setup [#verify-the-setup]

  Open your website in a browser with Developer Tools:

  1. **Open the Network tab** and filter by "analytics" or "script"
  2. **Verify the script loads**:
     * You should see a request to `/analytics/script.js` (not `app.rybbit.io`)
     * Status should be `200 OK`
     * The domain should be your own domain
  3. **Verify tracking works**:
     * Navigate to another page or trigger an event
     * You should see POST requests to `/analytics/track`
     * All requests should show your domain, not `app.rybbit.io`
  4. **Check the Rybbit dashboard**:
     * Wait 1-2 minutes for data processing
     * Verify your session appears in the real-time dashboard
</Steps>

## How It Works [#how-it-works]

The Rybbit tracking script has a built-in auto-discovery mechanism. When it loads from:

```html
<script src="/analytics/script.js" data-site-id="123"></script>
```

It automatically extracts the analytics host from its own `src` attribute:

```typescript
// Inside Rybbit's script
const scriptElement = document.currentScript;
const src = scriptElement.getAttribute('src');
const analyticsHost = src.split('/script.js')[0];
// Result: "" (empty string means same domain)
```

This means all tracking requests automatically go to `/analytics/track`, `/analytics/identify`, etc., which Next.js then rewrites to forward to Rybbit's servers.

## Performance Considerations [#performance-considerations]

### Bandwidth Usage [#bandwidth-usage]

All tracking requests now flow through your Next.js server, which will increase bandwidth usage:

<Callout type="warn">
  **Bandwidth Impact**: Each session typically uses 10-50 KB without session replay, or 50-500 KB with session replay enabled. For a site with 100,000 monthly sessions, expect 5-10 GB/month additional bandwidth without replay, or 30-80 GB/month with replay.
</Callout>

Most Vercel, Netlify, or other hosting plans can handle this, but check your plan's bandwidth limits if you have high traffic.

### Caching [#caching]

Next.js automatically caches responses when possible, but you can optimize further:

**Using Vercel Edge Network:**
If deployed on Vercel, your rewrites benefit from the global Edge Network, which caches static scripts close to users worldwide.

**Custom caching headers:**
The Rybbit server sets cache headers on its scripts, which Next.js respects:

* Scripts (`.js` files): Cached for 1 hour (`script.js`) to 1 day (`replay.js`, `metrics.js`)
* Configuration: Not cached by the server (you may cache it for \~5 minutes at your proxy if desired)
* Tracking POSTs: Not cached

### Server Load [#server-load]

Rewrites are handled at the edge on Vercel, so there's minimal impact on your serverless functions. For self-hosted Next.js, consider:

* Using a CDN (Cloudflare, CloudFront, etc.) in front of Next.js
* Scaling your server if you have very high traffic
* Monitoring server response times

## Troubleshooting [#troubleshooting]

### Script loads but events aren't tracked [#script-loads-but-events-arent-tracked]

**Problem**: You see the script load successfully, but no tracking data appears in the dashboard.

**Solution**:

1. Check that `/analytics/track` is included in your rewrites
2. Verify POST requests to `/analytics/track` return `200 OK` in Network tab
3. Check for CORS errors in the browser console
4. Ensure your Rybbit instance URL is correct in `.env.local`

### 404 errors on tracking endpoints [#404-errors-on-tracking-endpoints]

**Problem**: Script loads fine, but tracking requests return 404.

**Solution**:

1. Verify all tracking endpoints are in your `rewrites()` configuration
2. Restart your dev server after changing `next.config.js`
3. Clear your browser cache
4. Check that the endpoint paths exactly match (case-sensitive)

### Session replay not working [#session-replay-not-working]

**Problem**: Basic tracking works but session replay doesn't record.

**Solution**:
Add the session replay endpoints to your rewrites:

```javascript
{
  source: '/analytics/replay.js',
  destination: `${rybbitHost}/api/replay.js`,
},
{
  source: '/analytics/session-replay/record/:siteId',
  destination: `${rybbitHost}/api/session-replay/record/:siteId`,
},
```

### Environment variable not loading [#environment-variable-not-loading]

**Problem**: Rewrites don't work, console shows warning about missing `NEXT_PUBLIC_RYBBIT_HOST`.

**Solution**:

1. Ensure you created `.env.local` in your project root
2. Restart your dev server after creating `.env.local`
3. For production, ensure environment variables are set in your hosting platform (Vercel, Netlify, etc.)

## Deployment Considerations [#deployment-considerations]

### Vercel [#vercel]

When deploying to Vercel:

1. Add `NEXT_PUBLIC_RYBBIT_HOST` environment variable in your Vercel project settings
2. Rewrites automatically work at the edge with zero configuration
3. Bandwidth is generous on all Vercel plans

### Self-Hosted [#self-hosted]

When self-hosting Next.js:

1. Ensure environment variables are available to the Next.js process
2. Consider adding a CDN layer for better caching and reduced bandwidth
3. Monitor server load if you have high traffic

### Other Platforms (Netlify, AWS, etc.) [#other-platforms-netlify-aws-etc]

1. Set environment variables in your platform's settings
2. Verify rewrites are supported (most platforms support Next.js rewrites)
3. Check bandwidth limits for your plan

## Advanced Configuration [#advanced-configuration]

### Different paths for different environments [#different-paths-for-different-environments]

You can customize the proxy path based on the environment:

```javascript
// next.config.js
const nextConfig = {
  async rewrites() {
    const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;
    const analyticsPath = process.env.NODE_ENV === 'development'
      ? '/dev-analytics'
      : '/analytics';

    return [
      {
        source: `${analyticsPath}/script.js`,
        destination: `${rybbitHost}/api/script.js`,
      },
      // ... other rewrites
    ];
  },
};
```

### Conditional proxy (development only) [#conditional-proxy-development-only]

If you only want proxying in production:

```javascript
// next.config.js
const nextConfig = {
  async rewrites() {
    if (process.env.NODE_ENV === 'development') {
      return []; // No proxy in development
    }

    // ... production rewrites
  },
};
```

## Related Resources [#related-resources]

* [Next.js Integration Guide](/docs/guides/react/next-js) - General Next.js integration
* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Custom Events](/docs/track-events) - Track custom events
* [Next.js Rewrites Documentation](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) - Official Next.js docs


# Nginx Proxy Setup (/fr/docs/proxy-guide/nginx)





Nginx is a powerful web server and reverse proxy that makes it easy to proxy Rybbit tracking through your own domain. This guide shows how to configure Nginx to forward tracking requests to Rybbit servers while caching static scripts for better performance.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Nginx's `proxy_pass` directive lets you forward requests from your domain to Rybbit's servers. Combined with caching, this provides excellent performance and reliability for proxying analytics.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your domain
* Cache static scripts for better performance
* Forward necessary headers for accurate tracking
* Support all Rybbit features (session replay, Web Vitals, custom events)

## Prerequisites [#prerequisites]

* Nginx installed (version 1.18 or later recommended)
* SSL/TLS certificate configured (Let's Encrypt recommended)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID (found in your dashboard)

## Implementation [#implementation]

<Steps>
  ### Configure Nginx Proxy [#configure-nginx-proxy]

  Add a new location block (or update existing configuration) in your Nginx site configuration:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'With Cache Zone']">
    <Tab>
      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          listen 443 ssl http2;
          server_name yourdomain.com;

          # Your SSL configuration
          ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
          ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

          # Your main site configuration
          location / {
              # Your regular site config...
          }

          # Rybbit Analytics Proxy
          # Main tracking script (cached)
          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              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;

              # Cache for 1 hour
              proxy_cache_valid 200 1h;
              proxy_cache_bypass $http_cache_control;
              add_header X-Cache-Status $upstream_cache_status;
          }

          # Session replay script (cached)
          location = /analytics/replay.js {
              proxy_pass https://app.rybbit.io/api/replay.js;
              proxy_set_header Host app.rybbit.io;
              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;

              proxy_cache_valid 200 1h;
          }

          # Web Vitals metrics script (cached)
          location = /analytics/metrics.js {
              proxy_pass https://app.rybbit.io/api/metrics.js;
              proxy_set_header Host app.rybbit.io;
              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;

              proxy_cache_valid 200 1h;
          }

          # Event tracking endpoint (not cached)
          location = /analytics/track {
              proxy_pass https://app.rybbit.io/api/track;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;
          }

          # User identification endpoint (not cached)
          location = /analytics/identify {
              proxy_pass https://app.rybbit.io/api/identify;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;
          }

          # Session replay recording endpoint (not cached)
          location ~ ^/analytics/session-replay/record/(.*)$ {
              proxy_pass https://app.rybbit.io/api/session-replay/record/$1;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;

              # Allow larger uploads for session replay
              client_max_body_size 10M;
          }

          # Site configuration endpoint (cached briefly)
          location ~ ^/analytics/site/tracking-config/(.*)$ {
              proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
              proxy_set_header Host app.rybbit.io;
              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;

              # Cache for 5 minutes
              proxy_cache_valid 200 5m;
          }
      }
      ```

      <Callout type="info">
        Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
      </Callout>
    </Tab>

    <Tab>
      Minimal configuration for basic tracking:

      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          listen 443 ssl http2;
          server_name yourdomain.com;

          # SSL configuration
          ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
          ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

          # Main tracking script
          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;

              proxy_cache_valid 200 1h;
          }

          # Event tracking
          location = /analytics/track {
              proxy_pass https://app.rybbit.io/api/track;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;
          }
      }
      ```
    </Tab>

    <Tab>
      For better performance with caching, define a cache zone:

      ```nginx
      # /etc/nginx/nginx.conf (http block)
      http {
          # Define cache zone for Rybbit
          proxy_cache_path /var/cache/nginx/rybbit
              levels=1:2
              keys_zone=rybbit_cache:10m
              max_size=100m
              inactive=60m
              use_temp_path=off;

          # ... rest of http config
      }
      ```

      Then in your site config:

      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          # ... server config

          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;

              # Use the cache zone
              proxy_cache rybbit_cache;
              proxy_cache_valid 200 1h;
              proxy_cache_key "$scheme$request_method$host$request_uri";
              add_header X-Cache-Status $upstream_cache_status;
          }

          # ... other locations
      }
      ```
    </Tab>
  </Tabs>

  <Callout type="warn">
    **Important**: The `proxy_set_header X-Real-IP` and `X-Forwarded-For` headers are critical for accurate geolocation and user identification. Without these, all traffic will appear to come from your Nginx server's IP.
  </Callout>

  ### Create Cache Directory (Optional) [#create-cache-directory-optional]

  If using a cache zone, create the cache directory:

  ```bash
  sudo mkdir -p /var/cache/nginx/rybbit
  sudo chown www-data:www-data /var/cache/nginx/rybbit
  ```

  ### Test Nginx Configuration [#test-nginx-configuration]

  Before reloading Nginx, test the configuration for syntax errors:

  ```bash
  sudo nginx -t
  ```

  You should see:

  ```
  nginx: configuration file /etc/nginx/nginx.conf test is successful
  ```

  ### Reload Nginx [#reload-nginx]

  Apply the changes by reloading Nginx:

  ```bash
  sudo systemctl reload nginx
  ```

  Or if you prefer:

  ```bash
  sudo nginx -s reload
  ```

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to load the script from your proxied domain:

  ```html
  <!DOCTYPE html>
  <html>
  <head>
      <!-- ... other head elements -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      <!-- Your content -->
  </body>
  </html>
  ```

  Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.

  ### Verify the Setup [#verify-the-setup]

  Test your configuration:

  1. **Check Nginx is running**:
     ```bash
     sudo systemctl status nginx
     ```

  2. **Test script loading**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see:

     ```
     HTTP/2 200
     content-type: application/javascript
     x-cache-status: MISS  # First request
     ```

  3. **Test again to verify caching**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see:

     ```
     HTTP/2 200
     x-cache-status: HIT  # Cached!
     ```

  4. **Open your website** in a browser with Developer Tools and verify:
     * Script loads from `/analytics/script.js` (your domain)
     * Tracking requests go to `/analytics/track` (your domain)
     * Data appears in your Rybbit dashboard after 1-2 minutes
</Steps>

## How It Works [#how-it-works]

Nginx's `proxy_pass` directive transparently forwards requests to Rybbit's servers:

1. Browser requests `https://yourdomain.com/analytics/script.js`
2. Nginx matches the location block and forwards to `https://app.rybbit.io/api/script.js`
3. Nginx sets necessary headers (`X-Real-IP`, `X-Forwarded-For`) for accurate tracking
4. Response is cached (if configured) and sent back to browser
5. All subsequent tracking requests follow the same pattern

The Rybbit script auto-detects it's being served from your domain and sends all tracking data to your domain's `/analytics/*` endpoints.

## Performance Optimization [#performance-optimization]

### Caching Strategy [#caching-strategy]

Configure different cache durations based on content type:

```nginx
# Scripts - cache for 1 hour
location ~ ^/analytics/(script|replay|metrics)\.js$ {
    proxy_pass https://app.rybbit.io/api/$1.js;
    # ... proxy headers
    proxy_cache_valid 200 1h;
    proxy_cache_valid 404 1m;  # Cache 404s briefly
}

# Config - cache for 5 minutes (changes when you update dashboard settings)
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
    # ... proxy headers
    proxy_cache_valid 200 5m;
}

# Tracking - never cache (each request is unique)
location ~ ^/analytics/(track|identify)$ {
    proxy_pass https://app.rybbit.io/api/$1;
    # ... proxy headers
    # No caching directives
}
```

### Gzip Compression [#gzip-compression]

Enable compression for JavaScript files:

```nginx
# In http or server block
gzip on;
gzip_vary on;
gzip_types application/javascript text/javascript;
gzip_min_length 1000;
```

### Connection Pooling [#connection-pooling]

Keep connections to Rybbit backend alive for better performance:

```nginx
upstream rybbit_backend {
    server app.rybbit.io:443;
    keepalive 32;
}

location /analytics/ {
    proxy_pass https://rybbit_backend/api/;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    # ... other proxy headers
}
```

### Proxy Buffering [#proxy-buffering]

For better performance with larger session replay uploads:

```nginx
location ~ ^/analytics/session-replay/record/ {
    proxy_pass https://app.rybbit.io/api/session-replay/record/;
    # ... proxy headers

    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;
    proxy_busy_buffers_size 8k;
    client_max_body_size 10M;
}
```

## Security Considerations [#security-considerations]

### Rate Limiting [#rate-limiting]

Protect your proxy from abuse with rate limiting:

```nginx
# In http block
http {
    limit_req_zone $binary_remote_addr zone=analytics_limit:10m rate=10r/s;

    # ... rest of config
}

# In server block
location = /analytics/track {
    limit_req zone=analytics_limit burst=20 nodelay;
    proxy_pass https://app.rybbit.io/api/track;
    # ... proxy headers
}
```

This limits to 10 requests per second per IP, with bursts up to 20.

### Request Size Limits [#request-size-limits]

Set appropriate limits for different endpoints:

```nginx
# Default for most endpoints
client_max_body_size 1M;

# Larger limit for session replay
location ~ ^/analytics/session-replay/record/ {
    client_max_body_size 10M;
    # ... proxy config
}
```

### Security Headers [#security-headers]

Add security headers to your responses:

```nginx
add_header X-Content-Type-Options nosniff;
add_header X-Frame-Options DENY;
add_header Referrer-Policy strict-origin-when-cross-origin;
```

## Troubleshooting [#troubleshooting]

### 502 Bad Gateway [#502-bad-gateway]

**Problem**: Nginx returns 502 error when accessing analytics endpoints.

**Solution**:

1. Check Rybbit backend is accessible:
   ```bash
   curl -I https://app.rybbit.io/api/script.js
   ```
2. Verify `proxy_ssl_server_name on` is set
3. Check Nginx error logs:
   ```bash
   sudo tail -f /var/log/nginx/error.log
   ```

### Cache not working [#cache-not-working]

**Problem**: `X-Cache-Status` always shows `MISS`.

**Solution**:

1. Verify cache directory exists and is writable
2. Check `proxy_cache_path` is defined in http block
3. Ensure `proxy_cache` directive uses correct zone name
4. Check cache key is consistent:
   ```nginx
   proxy_cache_key "$scheme$request_method$host$request_uri";
   ```

### Incorrect geolocation in Rybbit [#incorrect-geolocation-in-rybbit]

**Problem**: All visitors show same location (your server's location).

**Solution**:
Ensure you're forwarding client IP headers:

```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
```

### SSL errors in Nginx logs [#ssl-errors-in-nginx-logs]

**Problem**: Logs show SSL verification errors when connecting to Rybbit.

**Solution**:
Add `proxy_ssl_server_name on` to enable SNI:

```nginx
location /analytics/ {
    proxy_pass https://app.rybbit.io/api/;
    proxy_ssl_server_name on;  # Enable SNI
    # ... other config
}
```

## Advanced Configuration [#advanced-configuration]

### Subdomain Proxy [#subdomain-proxy]

Use a dedicated subdomain for analytics:

```nginx
# /etc/nginx/sites-available/analytics.yourdomain.com
server {
    listen 443 ssl http2;
    server_name analytics.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/analytics.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.yourdomain.com/privkey.pem;

    # Proxy all requests to Rybbit
    location / {
        proxy_pass https://app.rybbit.io/api/;
        proxy_set_header Host app.rybbit.io;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_ssl_server_name on;
    }
}
```

Then use:

```html
<script src="https://analytics.yourdomain.com/script.js" data-site-id="123"></script>
```

### Multiple Rybbit Instances [#multiple-rybbit-instances]

If you need to proxy multiple Rybbit instances:

```nginx
location /analytics-prod/ {
    proxy_pass https://prod.rybbit.io/api/;
    # ... proxy config
}

location /analytics-staging/ {
    proxy_pass https://staging.rybbit.io/api/;
    # ... proxy config
}
```

## Related Resources [#related-resources]

* [Nginx Custom Configuration Guide](/docs/self-hosting-guides/custom-nginx) - Self-hosting Rybbit with Nginx
* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Framework-agnostic concepts
* [Nginx Proxy Module](http://nginx.org/en/docs/http/ngx_http_proxy_module.html) - Official Nginx documentation


# Troubleshooting Proxy Setup (/fr/docs/proxy-guide/troubleshooting)





This guide covers common issues you might encounter when setting up a Rybbit proxy and how to resolve them.

## Script Loading Issues [#script-loading-issues]

### Script Fails to Load (404 Error) [#script-fails-to-load-404-error]

**Symptoms:**

* Network tab shows 404 for `/analytics/script.js`
* Console errors about failed script loading
* No tracking data in dashboard

**Solutions:**

<Steps>
  ### Verify Proxy Configuration [#verify-proxy-configuration]

  Check your proxy rules are correctly configured:

  * **Next.js**: Ensure rewrites are in `next.config.js` and server is restarted
  * **Nginx**: Verify location blocks are active and Nginx is reloaded
  * **Caddy**: Check Caddyfile syntax with `caddy validate`
  * **Workers**: Verify route is configured in Cloudflare dashboard

  ### Check Path Mapping [#check-path-mapping]

  Ensure paths are correctly mapped:

  ```
  Your domain          →  Rybbit backend
  -----------------        ---------------
  /analytics/script.js →  /api/script.js
  ```

  Common mistakes:

  * Wrong source path (`/tracking` instead of `/analytics`)
  * Incorrect destination (missing `/api` prefix)
  * Typos in configuration

  ### Test Direct Backend Access [#test-direct-backend-access]

  Verify Rybbit backend is accessible:

  ```bash
  curl -I https://app.rybbit.io/api/script.js
  ```

  Should return `HTTP/2 200` with `content-type: application/javascript`.
</Steps>

***

### Script Loads but Returns HTML [#script-loads-but-returns-html]

**Symptoms:**

* Script loads with 200 status
* Content-Type is `text/html` instead of `application/javascript`
* Console errors about unexpected token `<`

**Cause:** Proxy is serving your application's 404 page instead of proxying.

**Solutions:**

1. **Ensure proxy runs before app routing**:
   * Next.js: Rewrites run automatically before pages
   * Express: Define proxy routes BEFORE catch-all routes
   * Laravel: Place proxy routes at the top of `web.php`

2. **Check route specificity**:

```javascript
// ❌ Wrong order - catch-all comes first
app.get('*', (req, res) => res.sendFile('index.html'));
app.use('/analytics', proxyMiddleware);

// ✅ Correct order - proxy comes first
app.use('/analytics', proxyMiddleware);
app.get('*', (req, res) => res.sendFile('index.html'));
```

***

## Tracking Issues [#tracking-issues]

### Script Loads but No Events Tracked [#script-loads-but-no-events-tracked]

**Symptoms:**

* Script loads successfully
* No errors in console
* No tracking data appears in Rybbit dashboard
* POST requests to `/analytics/track` fail or return errors

**Solutions:**

<Steps>
  ### Verify All Endpoints Are Proxied [#verify-all-endpoints-are-proxied]

  Ensure tracking endpoints are configured:

  * `/analytics/track` (required)
  * `/analytics/identify` (for user identification)
  * `/analytics/session-replay/record/:siteId` (for session replay)
  * `/analytics/site/tracking-config/:siteId` (for configuration)

  **Check Network tab**: Look for failed POST requests to `/analytics/track`.

  ### Check CORS Headers [#check-cors-headers]

  Tracking endpoints need proper CORS headers. Rybbit sets these automatically, but ensure your proxy preserves them:

  ```nginx
  # Nginx - preserve CORS headers
  proxy_pass_header Access-Control-Allow-Origin;
  proxy_pass_header Access-Control-Allow-Methods;
  ```

  ```javascript
  // Express - don't override CORS
  // ❌ Wrong - blocks CORS
  app.use('/analytics', cors({ origin: 'https://yourdomain.com' }));

  // ✅ Correct - allow all origins (or use Rybbit's headers)
  app.use('/analytics', cors({ origin: true }));
  ```

  ### Verify Content-Type for POST Requests [#verify-content-type-for-post-requests]

  Tracking POSTs send JSON data. Ensure Content-Type is preserved:

  ```nginx
  # Nginx
  proxy_set_header Content-Type $content_type;
  ```

  ```javascript
  // Express
  onProxyReq: (proxyReq, req) => {
    if (req.headers['content-type']) {
      proxyReq.setHeader('Content-Type', req.headers['content-type']);
    }
  }
  ```

  ### Check Request Method Preservation [#check-request-method-preservation]

  Ensure POST requests remain POST:

  ```nginx
  # Nginx - correct
  proxy_method $request_method;

  # Or let it default (preserves method)
  proxy_pass https://app.rybbit.io;
  ```
</Steps>

***

### Events Tracked but Dashboard Shows Wrong Data [#events-tracked-but-dashboard-shows-wrong-data]

**Symptoms:**

* Events appear in dashboard
* But geolocation is wrong (all same location)
* Or user agents are incorrect

**Cause:** Client IP or headers not forwarded properly.

**Solutions:**

<Callout type="warn">
  **Critical**: The `X-Forwarded-For` header must contain the original client IP for accurate geolocation and user identification, and the **First-Party Proxy** toggle must be enabled in your site settings. Don't rely on `X-Real-IP` — on Rybbit Cloud it never reaches the backend (our edge network consumes it), and AWS CloudFront cannot send it at all.
</Callout>

**Nginx:**

```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header User-Agent $http_user_agent;
```

**Caddy:**

```txt
reverse_proxy https://app.rybbit.io {
    header_up X-Real-IP {remote_host}
    header_up X-Forwarded-For {remote_host}
}
```

**Express:**

```javascript
onProxyReq: (proxyReq, req) => {
  const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  proxyReq.setHeader('X-Real-IP', clientIp);
  proxyReq.setHeader('X-Forwarded-For', clientIp);
  proxyReq.setHeader('User-Agent', req.headers['user-agent']);
}
```

**Cloudflare Workers:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';
proxyHeaders.set('X-Forwarded-For', clientIp);
```

***

### Proxied Requests Are Detected as Bots [#proxied-requests-are-detected-as-bots]

**Symptoms:**

* `/analytics/track` returns `200 OK`
* Events do not appear in the normal analytics dashboard (only under bot traffic)
* Tracking works fine when the script talks to Rybbit directly, without the proxy

There are two independent causes, and server-side proxies often hit **both**. Work through them in order.

#### Cause 1: Your proxy strips the browser's headers [#cause-1-your-proxy-strips-the-browsers-headers]

Rybbit's bot detection scores requests on headers that every real browser sends: `Accept`, `Accept-Language`, `Accept-Encoding` (with `gzip`), and the `Sec-Fetch-*` headers that all Chromium browsers attach. A proxy that forwards only `User-Agent` and the visitor IP produces requests indistinguishable from a script — they are accepted with `200 OK` but classified as bots.

**Fix:** forward **all** incoming request headers, minus `Host` and hop-by-hop headers (`Connection`, `Content-Length`). Hand-picking headers is the most common mistake in PHP/WordPress-style proxies.

```php
// PHP example — forward everything except Host/hop-by-hop
$headers = [];
foreach (getallheaders() as $name => $value) {
    if (!in_array(strtolower($name), ['host', 'connection', 'content-length'])) {
        $headers[] = "$name: $value";
    }
}
$headers[] = 'X-Forwarded-For: ' . $_SERVER['REMOTE_ADDR'];
```

#### Cause 2: Rybbit sees your proxy's IP instead of the visitor's [#cause-2-rybbit-sees-your-proxys-ip-instead-of-the-visitors]

First-party proxies typically run on hosting/datacenter infrastructure, so if the visitor IP is not forwarded (or not trusted), traffic carries a datacenter ASN and reinforces bot classification — and geolocation points at your proxy's region.

**Fix:**

1. Set `X-Forwarded-For` to the original visitor IP before forwarding to Rybbit.
2. Enable the **First-Party Proxy** toggle in **Site Settings → Privacy & Security** so Rybbit trusts the forwarded IP unconditionally.

<Callout type="warn">
  Use `X-Forwarded-For`, not `X-Real-IP`. On Rybbit Cloud, `X-Real-IP` never reaches the backend (our edge network consumes it), and AWS CloudFront cannot send it at all.
</Callout>

**Cloudflare Workers:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

const proxyHeaders = new Headers(request.headers); // preserves all browser headers
proxyHeaders.set('X-Forwarded-For', clientIp);
```

**AWS CloudFront:**

* Set `X-Forwarded-For` to the viewer IP from a CloudFront Function/Lambda\@Edge
* Configure the origin request policy to forward all viewer headers

```javascript
// CloudFront Function (viewer-request)
function handler(event) {
  event.request.headers["x-forwarded-for"] = { value: event.viewer.ip };
  return event.request;
}
```

***

## Session Replay Issues [#session-replay-issues]

### Session Replay Not Working [#session-replay-not-working]

**Symptoms:**

* Basic tracking works fine
* Session replays don't appear in dashboard
* Console shows errors loading `/analytics/replay.js`

**Solutions:**

1. **Add replay script endpoint**:

```javascript
// Next.js
{
  source: '/analytics/replay.js',
  destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/replay.js`,
}
```

2. **Add replay recording endpoint**:

```javascript
{
  source: '/analytics/session-replay/record/:siteId',
  destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/session-replay/record/:siteId`,
}
```

3. **Increase request size limits**:

Session replay can send large payloads (up to 10MB). Ensure your proxy allows this:

```nginx
# Nginx
location ~ ^/analytics/session-replay/record/ {
    client_max_body_size 10M;
    proxy_pass https://app.rybbit.io;
}
```

```javascript
// Express
app.use('/analytics/session-replay', express.json({ limit: '10mb' }));
```

```javascript
// Next.js - add to next.config.js
module.exports = {
  api: {
    bodyParser: {
      sizeLimit: '10mb',
    },
  },
};
```

***

## Configuration and Caching Issues [#configuration-and-caching-issues]

### Stale Configuration (Settings Changes Not Applied) [#stale-configuration-settings-changes-not-applied]

**Symptoms:**

* Changed settings in Rybbit dashboard
* But tracking script still uses old settings
* Takes a long time for changes to appear

**Cause:** Configuration endpoint is cached too aggressively.

**Solutions:**

1. **Check cache duration** for config endpoint:

```nginx
# Nginx - cache for 5 minutes max
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_cache_valid 200 5m;  # Not longer!
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
}
```

2. **Clear cache manually**:

```bash
# Nginx
sudo nginx -s reload

# Or clear cache directory
sudo rm -rf /var/cache/nginx/rybbit/*
```

```javascript
// Node.js/Express with node-cache
cache.del(`rybbit_config_${siteId}`);

// Or flush all
cache.flushAll();
```

3. **Don't cache config endpoint at all** (if issues persist):

```nginx
# Nginx - no caching
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_cache off;
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
}
```

***

### Script Updates Not Appearing [#script-updates-not-appearing]

**Symptoms:**

* Rybbit released an update
* Your site still loads old script version
* Missing new features or bug fixes

**Cause:** Script cached too long.

**Solutions:**

1. **Recommended cache duration**: 1 hour maximum

```nginx
# Nginx
proxy_cache_valid 200 1h;  # Not longer!
```

2. **Clear script cache**:

```bash
# Nginx - purge cache
sudo rm -rf /var/cache/nginx/rybbit/
sudo nginx -s reload
```

```bash
# Vercel - clear via dashboard
# Deployments → Your deployment → Clear cache
```

```javascript
// Cloudflare Workers - purge via dashboard
// Caching → Configuration → Purge Everything
```

3. **Add cache busting** (advanced):

```javascript
// Next.js - revalidate on each deployment
{
  source: '/analytics/script.js',
  destination: `${rybbitHost}/api/script.js`,
  headers: [
    {
      key: 'Cache-Control',
      value: 'public, max-age=3600, must-revalidate',
    },
  ],
}
```

***

## Performance Issues [#performance-issues]

### High Bandwidth Usage [#high-bandwidth-usage]

**Symptoms:**

* Bandwidth costs increasing significantly
* Server struggling with traffic
* Slow response times

**Solutions:**

<Steps>
  ### Implement Caching [#implement-caching]

  Cache static scripts to reduce backend requests:

  ```nginx
  # Nginx with caching
  proxy_cache_path /var/cache/nginx/rybbit levels=1:2 keys_zone=rybbit:10m;

  location = /analytics/script.js {
      proxy_cache rybbit;
      proxy_cache_valid 200 1h;
      proxy_cache_key "$scheme$request_method$host$request_uri";
      add_header X-Cache-Status $upstream_cache_status;
      proxy_pass https://app.rybbit.io/api/script.js;
  }
  ```

  ### Use CDN [#use-cdn]

  Put a CDN in front of your proxy:

  * Cloudflare (recommended)
  * AWS CloudFront
  * Fastly

  ### Monitor and Limit [#monitor-and-limit]

  Add monitoring and rate limiting:

  ```javascript
  // Express with rate limiting
  const rateLimit = require('express-rate-limit');

  app.use('/analytics/track', rateLimit({
    windowMs: 60 * 1000,
    max: 100, // 100 requests per minute per IP
  }));
  ```
</Steps>

***

### Slow Response Times [#slow-response-times]

**Symptoms:**

* Tracking requests take multiple seconds
* Script loading is slow
* Poor user experience

**Solutions:**

1. **Enable compression**:

```nginx
# Nginx
gzip on;
gzip_types application/javascript;
```

2. **Use connection keepalive**:

```nginx
# Nginx
proxy_http_version 1.1;
proxy_set_header Connection "";

upstream rybbit {
    server app.rybbit.io:443;
    keepalive 32;
}
```

3. **Check backend connectivity**:

```bash
# Test latency to Rybbit
curl -w "@curl-format.txt" -o /dev/null -s https://app.rybbit.io/api/script.js

# Create curl-format.txt:
# time_namelookup:  %{time_namelookup}s
# time_connect:     %{time_connect}s
# time_starttransfer: %{time_starttransfer}s
# time_total:       %{time_total}s
```

If backend is slow, consider:

* Self-hosting Rybbit closer to your users
* Using a CDN proxy
* Caching more aggressively

***

## Platform-Specific Issues [#platform-specific-issues]

### Next.js: Rewrites Not Working [#nextjs-rewrites-not-working]

**Problem:** Added rewrites to `next.config.js` but they don't work.

**Solutions:**

1. **Restart dev server**:

```bash
# Stop server (Ctrl+C)
npm run dev
```

2. **Check async rewrites** function:

```javascript
// ❌ Wrong - not async
rewrites() {
    return [...];
}

// ✅ Correct - async
async rewrites() {
    return [...];
}
```

3. **Verify environment variable** is loaded:

```javascript
async rewrites() {
    console.log('RYBBIT_HOST:', process.env.NEXT_PUBLIC_RYBBIT_HOST);
    // Should log the URL
    return [...];
}
```

***

### Nginx: 502 Bad Gateway [#nginx-502-bad-gateway]

**Problem:** Nginx returns 502 error for analytics endpoints.

**Solutions:**

1. **Enable SNI** for SSL:

```nginx
proxy_ssl_server_name on;
```

2. **Check DNS resolution**:

```bash
nslookup app.rybbit.io
```

3. **Check logs**:

```bash
sudo tail -f /var/log/nginx/error.log
```

4. **Test backend directly**:

```bash
curl -v https://app.rybbit.io/api/script.js
```

***

### Vercel: 404 After Deployment [#vercel-404-after-deployment]

**Problem:** Works locally but 404 in production.

**Solutions:**

1. **Ensure `vercel.json` is committed**:

```bash
git add vercel.json
git commit -m "Add Rybbit proxy config"
git push
```

2. **Check build logs** in Vercel dashboard for errors

3. **Verify environment variables** are set in Vercel project settings

***

## Debugging Checklist [#debugging-checklist]

When troubleshooting, work through this checklist:

* [ ] Script loads successfully (200 status, correct Content-Type)
* [ ] Tracking endpoint is proxied (`/analytics/track`)
* [ ] POST requests preserve method and body
* [ ] Client IP is forwarded in `X-Forwarded-For` (not just `X-Real-IP` — that header doesn't survive Rybbit Cloud's edge)
* [ ] **First-Party Proxy** toggle is enabled in Site Settings → Privacy & Security
* [ ] Full browser header set is forwarded (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — not just `User-Agent`
* [ ] User-Agent header is preserved
* [ ] CORS headers are preserved (check response headers)
* [ ] Request size limits allow tracking data (1MB minimum)
* [ ] Session replay endpoints are proxied (if using replay)
* [ ] Cache duration is appropriate (1 hour for scripts, 5 min for config)
* [ ] No CSRF protection blocking POST requests
* [ ] Environment variables are set correctly
* [ ] Configuration changes have been deployed

## Getting Help [#getting-help]

If you've tried everything and still have issues:

1. **Check browser console** for JavaScript errors
2. **Check Network tab** for failed requests (note status codes)
3. **Check server logs** for proxy errors
4. **Test with curl** to isolate browser vs server issues
5. **Verify directly** against `https://app.rybbit.io/api/script.js`

**Gather this information before asking for help:**

* Framework/platform you're using
* Proxy configuration code
* Network tab screenshot showing the issue
* Any error messages from logs or console
* Whether it worked before (what changed?)

## Related Resources [#related-resources]

* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [Tracking Script Documentation](/docs/script) - Script configuration
* Framework-specific guides for detailed setup


# Vercel Proxy Setup (/fr/docs/proxy-guide/vercel)





Vercel makes it easy to proxy Rybbit tracking through their Edge Network. If you're using Next.js, follow the [Next.js proxy guide](/docs/proxy-guide/next-js) instead, which is optimized for Next.js applications.

This guide is for static sites or other frameworks deployed on Vercel.

<Callout type="info">
  Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**. Rewrites on this platform automatically forward the browser's headers and set `X-Forwarded-For` to the visitor IP — the toggle tells Rybbit to trust that forwarded IP directly.
</Callout>

## Overview [#overview]

Vercel supports rewrites in `vercel.json`, allowing you to proxy requests through their global Edge Network. This provides excellent performance with automatic caching at edge locations worldwide.

**What you'll achieve:**

* Proxy Rybbit through Vercel's Edge Network
* Automatic global caching and CDN distribution
* Simple JSON configuration
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Site deployed on Vercel
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Create or Update vercel.json [#create-or-update-verceljson]

  Add rewrites to your `vercel.json` file in the project root:

  ```json
  {
    "rewrites": [
      {
        "source": "/analytics/script.js",
        "destination": "https://app.rybbit.io/api/script.js"
      },
      {
        "source": "/analytics/replay.js",
        "destination": "https://app.rybbit.io/api/replay.js"
      },
      {
        "source": "/analytics/metrics.js",
        "destination": "https://app.rybbit.io/api/metrics.js"
      },
      {
        "source": "/analytics/track",
        "destination": "https://app.rybbit.io/api/track"
      },
      {
        "source": "/analytics/identify",
        "destination": "https://app.rybbit.io/api/identify"
      },
      {
        "source": "/analytics/session-replay/record/:siteId",
        "destination": "https://app.rybbit.io/api/session-replay/record/:siteId"
      },
      {
        "source": "/analytics/site/tracking-config/:siteId",
        "destination": "https://app.rybbit.io/api/site/tracking-config/:siteId"
      }
    ]
  }
  ```

  <Callout type="info">
    Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to use the proxied path:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Deploy to Vercel [#deploy-to-vercel]

  Commit your changes and deploy:

  ```bash
  git add vercel.json
  git commit -m "Add Rybbit proxy configuration"
  git push
  ```

  Vercel will automatically detect the changes and deploy with the new rewrites.

  ### Verify the Setup [#verify-the-setup]

  1. **Visit your deployed site** with Developer Tools open
  2. **Check Network tab**:
     * Script should load from `/analytics/script.js`
     * Tracking requests should go to `/analytics/track`
     * All requests should show your Vercel domain
  3. **Verify in Rybbit dashboard**: Data should appear after 1-2 minutes
</Steps>

## How It Works [#how-it-works]

Vercel's Edge Network handles rewrites at the edge, close to your users:

1. Request hits Vercel's edge location nearest to the user
2. Edge server rewrites and proxies to Rybbit
3. Response is cached at the edge (for cacheable requests)
4. Subsequent requests serve from edge cache

This provides excellent performance with minimal configuration.

## Performance Benefits [#performance-benefits]

### Edge Network Caching [#edge-network-caching]

Vercel automatically caches responses at edge locations:

* **Scripts**: Cached globally, served from nearest edge
* **Configuration**: Cached with appropriate TTL
* **Tracking requests**: Not cached (unique per request)

### Global Distribution [#global-distribution]

Your analytics proxy benefits from Vercel's global CDN:

* 70+ edge locations worldwide
* Sub-100ms latency for most users
* Automatic failover and redundancy

## Bandwidth Considerations [#bandwidth-considerations]

<Callout type="warn">
  Vercel rewrites count toward your bandwidth quota. For a site with 100,000 monthly sessions:

  * Without session replay: \~5-10 GB/month
  * With session replay: \~30-80 GB/month

  Check your Vercel plan limits. Pro plan includes 1 TB bandwidth/month.
</Callout>

## Troubleshooting [#troubleshooting]

### Rewrites not working [#rewrites-not-working]

**Problem**: Requests still go to `app.rybbit.io` directly.

**Solution**:

1. Ensure `vercel.json` is in your project root
2. Redeploy after adding `vercel.json`
3. Clear browser cache and test in incognito mode

### 404 on tracking endpoints [#404-on-tracking-endpoints]

**Problem**: Script loads but tracking returns 404.

**Solution**:
Verify all endpoints are in `vercel.json` rewrites, including:

* `/analytics/track`
* `/analytics/identify`
* `/analytics/session-replay/record/:siteId`

### Session replay not working [#session-replay-not-working]

**Problem**: Basic tracking works but replay doesn't record.

**Solution**:
Add replay endpoints to rewrites:

```json
{
  "source": "/analytics/replay.js",
  "destination": "https://app.rybbit.io/api/replay.js"
},
{
  "source": "/analytics/session-replay/record/:siteId",
  "destination": "https://app.rybbit.io/api/session-replay/record/:siteId"
}
```

## Environment-Specific Configuration [#environment-specific-configuration]

### Using Environment Variables [#using-environment-variables]

While Vercel's `vercel.json` doesn't support environment variables directly, you can use different config files:

```json
// vercel.json (production)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}
```

```json
// vercel.staging.json (staging)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://staging.rybbit.io/api/script.js"
    }
  ]
}
```

Then specify config in build settings or use Vercel CLI:

```bash
vercel --prod --local-config vercel.json
```

## Advanced Configuration [#advanced-configuration]

### Headers [#headers]

Add custom headers to responses:

```json
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ],
  "headers": [
    {
      "source": "/analytics/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=3600"
        }
      ]
    }
  ]
}
```

### Redirects vs Rewrites [#redirects-vs-rewrites]

Don't use redirects for proxying (they're visible to the user):

```json
// ❌ Wrong - uses redirects (user sees app.rybbit.io)
{
  "redirects": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}

// ✅ Correct - uses rewrites (transparent proxy)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}
```

## Related Resources [#related-resources]

* [Next.js Proxy Guide](/docs/proxy-guide/next-js) - If using Next.js
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Vercel Rewrites Documentation](https://vercel.com/docs/projects/project-configuration#rewrites) - Official Vercel docs


# JavaScript (Node.js) (/fr/docs/sdks/node)





## Installation [#installation]

```bash filename="npm"
npm install @rybbit/node
```

```bash filename="yarn"
yarn add @rybbit/node
```

## Initialization [#initialization]

### Syntax [#syntax]

```typescript
import { Rybbit } from "@rybbit/node";

const rybbit = new Rybbit(config: RybbitConfig);
```

### Example [#example]

```javascript
import { Rybbit } from "@rybbit/node";

const rybbit = new Rybbit({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  apiKey: "your-secret-api-key",
});
```

<Callout type="warning">
  The `Rybbit` constructor will throw an error if required configuration options (`analyticsHost`, `siteId`, `apiKey`) are missing or invalid.
</Callout>

### Configuration Options [#configuration-options]

| Option          | Type               | Default | Description                                                                                      |
| :-------------- | :----------------- | :------ | :----------------------------------------------------------------------------------------------- |
| `analyticsHost` | `string`           | -       | **Required.** URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |
| `siteId`        | `string \| number` | -       | **Required.** The Site ID for your website obtained from your Rybbit instance.                   |
| `apiKey`        | `string`           | -       | **Required.** Your secret API key for the site                                                   |
| `debug`         | `boolean`          | `false` | Enable detailed logging to the console.                                                          |

## Tracking Pageviews [#tracking-pageviews]

While pageviews are traditionally a browser concept, the Node.js SDK provides a `pageview` method to track events that are analogous to a user viewing a page or a significant resource. This can be useful for tracking views of server-rendered pages before client-side JavaScript takes over, or for tracking views of API resources.

### Syntax [#syntax-1]

```typescript
await rybbit.pageview(payload?: Payload);
```

### Parameters [#parameters]

* **`payload`** (`object`, Optional): An object containing details about the pageview. All properties are optional.
  * `hostname` (`string`): The hostname associated with this pageview.
  * `pathname` (`string`): The path of the page/resource being viewed.
  * `querystring` (`string`): Any query parameters associated with the path.
  * `screenWidth` (`number`): Screen width in pixels.
  * `screenHeight` (`number`): Screen height in pixels.
  * `language` (`string`): Language code.
  * `page_title` (`string`): The title of the page or resource.
  * `referrer` (`string`): The referrer URL.
  * `user_id` (`string`): A unique identifier for the user.
  * `user_agent` (`string`): The user agent string of the client.
  * `ip_address` (`string`): The IP address of the client.

<Callout type="info">
  The fields `screenWidth`, `screenHeight`, `language`, `page_title`, and `referrer` are typically browser-derived. When using the Node.js SDK, you would only provide these if they are relevant and available in your server-side context. For many server-side pageview events, `hostname` and `pathname` might be the most relevant.
</Callout>

### Example [#example-1]

```javascript
// Track a server-rendered page view
async function handleProductPageRequest(req, res) {
  // ... server logic to render product page ...

  await rybbit.pageview({
    hostname: req.hostname,
    pathname: `/products/${req.params.productId}`,
    page_title: `Product - ${product.name}`,
    ip_address: req.ip
  });

  // ... send response ...
}

// Track an API resource view
async function serveApiResource(req) {
  await rybbit.pageview({
    hostname: "api.myservice.com",
    pathname: `/v1/items/${req.params.itemId}`,
    user_id: req.user.id,
    ip_address: req.ip
  });
  // ... return API data ...
}
```

## Tracking Custom Events [#tracking-custom-events]

Use custom events to track specific actions or milestones occurring in your backend system. Examples include user account creation, background job completion, API endpoint usage, or any significant server-side process.

### Syntax [#syntax-2]

```typescript
await rybbit.event(eventName: string, payload?: Payload, properties?: TrackProperties);
```

### Parameters [#parameters-1]

* **`eventName`** (`string`, Required): The name of the event you want to track.
* **`payload`** (`object`, Optional): An object containing contextual details for the event. All properties are optional.
  * `hostname` (`string`): The hostname associated with this event.
  * `pathname` (`string`): The path or resource context for this event.
  * `querystring` (`string`): Any query parameters relevant to the event's context.
  * `screenWidth` (`number`): Screen width in pixels.
  * `screenHeight` (`number`): Screen height in pixels.
  * `language` (`string`): Language code.
  * `page_title` (`string`): The title of the page or resource context.
  * `referrer` (`string`): The referrer URL.
  * `user_id` (`string`): A unique identifier for the user.
  * `user_agent` (`string`): The user agent string of the client.
  * `ip_address` (`string`): The IP address of the client.
* **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values can be a `string`, `number`, `boolean`, or an array of these types.

<Callout type="info">
  The `payload` fields (`hostname`, `pathname`, etc.) provide general context for the event, similar to a pageview. The `properties` object is for data specific to the custom `eventName` itself (e.g., for an `"order_processed"` event, properties might include `orderId: 12345` and `totalAmount: 99.99`).
</Callout>

### Example [#example-2]

```javascript
// Track a new user registration
async function registerUser(userData, req) {
  // ... process user registration ...

  await rybbit.event("user_registered",
    {
      hostname: "auth.myservice.com",
      pathname: "/register",
      ip_address: req.ip
    },
    {
      userId: newUserId,
      registrationMethod: "email"
    }
  );
}

// Track a background job completion
async function processDailyReport(reportId) {
  // ... generate report ...

  await rybbit.event("report_generated",
    {},
    {
      reportId: reportId,
      status: "success",
      processingTimeMs: 12345
    }
  );
}

// Track an API endpoint usage with specific data
async function handleApiRequest(req) {
    // ... handle request ...
    await rybbit.event(
        "api_v1_item_lookup",
        {
          hostname: req.hostname,
          pathname: req.path,
          user_id: req.user.id,
          ip_address: req.ip
        },
        {
          itemId: req.params.itemId,
          clientVersion: req.headers["x-client-version"]
        }
    );
    // ... return response ...
}
```


# React Native (/fr/docs/sdks/react-native)





The `@rybbit/react-native` SDK lets you track screens, events, errors, and users in React Native apps. Mobile sites get an App Analytics dashboard mode with mobile-specific labels (e.g. screen views instead of pageviews).

## Creating a Mobile App Site [#creating-a-mobile-app-site]

Before installing the SDK, create a site for your app in the Rybbit dashboard:

1. Click **Add Site** and select the **React Native app** option instead of Website.
2. Enter an app identifier (e.g. `com.example.app`). Letters, numbers, dots, hyphens, and underscores are allowed.
3. Copy the Site ID — you'll pass it to `init()`.

## Installation [#installation]

```bash
npm install @rybbit/react-native @react-native-async-storage/async-storage
```

<Callout type="info">
  `@react-native-async-storage/async-storage` is recommended but not strictly required. The SDK accepts any storage adapter with `getItem`/`setItem`/`removeItem`. Without one, it falls back to in-memory storage and the anonymous visitor ID will not persist across app launches, so every launch counts as a new visitor.
</Callout>

## Initialization [#initialization]

<Callout type="warning">
  `rybbit.init()` **must** be called once before any other tracking methods. Calling other methods first throws an error.
</Callout>

### Syntax [#syntax]

```typescript
async rybbit.init(config: RybbitConfig): Promise<void>;
```

### Example [#example]

```tsx
import AsyncStorage from "@react-native-async-storage/async-storage";
import rybbit from "@rybbit/react-native";

await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  appIdentifier: "com.example.app",
  appVersion: "1.4.2",
  storage: AsyncStorage,
  initialScreenName: "Home",
});
```

### Configuration Options [#configuration-options]

#### Required Options [#required-options]

| Option          | Type               | Description                                                                    |
| :-------------- | :----------------- | :----------------------------------------------------------------------------- |
| `analyticsHost` | `string`           | URL of your Rybbit instance's API (e.g., `https://rybbit.yourdomain.com/api`). |
| `siteId`        | `string \| number` | The Site ID for your app obtained from your Rybbit instance.                   |

#### Optional Options [#optional-options]

| Option                  | Type            | Default     | Description                                                                                                                          |
| :---------------------- | :-------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `appIdentifier`         | `string`        | `""`        | Identifier for your app (e.g., `com.example.app`). Used as the hostname in tracked data. Falls back to `bundleId`, then the site ID. |
| `bundleId`              | `string`        | `""`        | Alias for `appIdentifier`; used when `appIdentifier` is not set.                                                                     |
| `appVersion`            | `string`        | `""`        | Your app's version. Appended to the synthetic user agent sent with each event.                                                       |
| `tag`                   | `string`        | `""`        | A tag added to every event, useful for segmenting data (e.g., by environment or build channel).                                      |
| `storage`               | `RybbitStorage` | in-memory   | Storage adapter used to persist the anonymous visitor ID and identified user ID. Pass `AsyncStorage` or any compatible object.       |
| `storageKeyPrefix`      | `string`        | `"@rybbit"` | Prefix for storage keys. Keys are namespaced per site: `{prefix}:{siteId}:anonymous-id`.                                             |
| `debug`                 | `boolean`       | `false`     | Log SDK warnings (failed requests, config fetch failures) to the console.                                                            |
| `autoTrackAppLifecycle` | `boolean`       | `true`      | Automatically track `app_open` and `app_background` events on `AppState` changes. See [App Lifecycle Events](#app-lifecycle-events). |
| `initialScreenName`     | `string`        | `""`        | If set, a screen view for this name is tracked during `init()` (unless Track Initial Pageview is disabled in your dashboard).        |
| `configTimeoutMs`       | `number`        | `3000`      | Timeout in milliseconds for fetching remote tracking config during `init()`. On timeout or failure, the SDK proceeds with defaults.  |
| `maxQueueSize`          | `number`        | `100`       | Maximum number of failed events kept in the in-memory retry queue. See [Offline Handling](#offline-handling-and-retries).            |
| `fetch`                 | `typeof fetch`  | global      | Custom `fetch` implementation. Defaults to the global `fetch`.                                                                       |

#### Remote Configuration [#remote-configuration]

During `init()`, the SDK fetches your site's tracking settings from the dashboard. Two of them affect the React Native SDK:

| Dashboard Setting      | Effect                                                                     |
| :--------------------- | :------------------------------------------------------------------------- |
| Track Initial Pageview | When disabled, the `initialScreenName` screen view is not tracked on init. |
| Capture Errors         | When disabled, calls to `rybbit.error()` are silently ignored.             |

Web-only settings (session replay, Web Vitals, outbound links, autocapture) do not apply to mobile apps.

## Tracking Screens [#tracking-screens]

Screens are the mobile equivalent of pageviews. Each screen view is tracked with the screen name as both the path and title.

### Syntax [#syntax-1]

```typescript
rybbit.screen(name: string, properties?: TrackProperties, context?: TrackContext): Promise<void>;
```

### Parameters [#parameters]

* **`name`** (`string`, Required): The screen name (e.g., `"Home"`, `"Checkout"`). Used as the pathname (`/Home`) and page title.
* **`properties`** (`object`, Optional): Additional key-value pairs attached to the screen view.
* **`context`** (`object`, Optional): Overrides for the tracked payload. See [Track Context](#track-context).

### Example [#example-1]

```tsx
await rybbit.screen("Checkout");

// With properties and an explicit path
await rybbit.screen("Product", { productId: "sku-123" }, { pathname: "/products/sku-123" });
```

You can also track a raw path directly, mirroring the web SDK:

```typescript
rybbit.pageview(path?: string, context?: TrackContext): Promise<void>;
```

## React Navigation [#react-navigation]

The SDK ships a navigation tracker that hooks into React Navigation's `NavigationContainer` and automatically tracks a screen view whenever the active route changes. Consecutive events for the same route name are deduplicated.

```tsx
import { NavigationContainer, useNavigationContainerRef } from "@react-navigation/native";
import rybbit from "@rybbit/react-native";

const navigationTracker = rybbit.createNavigationTracker();

function App() {
  const navigationRef = useNavigationContainerRef();

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => navigationTracker.onReady(navigationRef)}
      onStateChange={() => navigationTracker.onStateChange(navigationRef)}
    >
      {/* screens */}
    </NavigationContainer>
  );
}
```

### Options [#options]

```typescript
rybbit.createNavigationTracker(options?: NavigationTrackerOptions): NavigationTracker;
```

| Option               | Type                | Default                      | Description                                                                |
| :------------------- | :------------------ | :--------------------------- | :------------------------------------------------------------------------- |
| `includeRouteParams` | `boolean`           | `false`                      | Include the route's params as a `routeParams` property on the screen view. |
| `getRouteName`       | `(route) => string` | `route.name`                 | Customize how the screen name is derived from the current route.           |
| `getPath`            | `(route) => string` | `route.path` or `route.name` | Customize the tracked pathname for the current route.                      |

The returned tracker exposes `onReady`, `onStateChange`, and `trackCurrentRoute` — all take the navigation ref and track the current route if it changed. It works with any navigation library whose ref exposes a `getCurrentRoute()` method.

<Callout type="warning">
  Route params can contain sensitive data (IDs, tokens, emails). Only enable `includeRouteParams` if your route params are safe to store in analytics.
</Callout>

## Tracking Custom Events [#tracking-custom-events]

### Syntax [#syntax-2]

```typescript
rybbit.event(name: string, properties?: TrackProperties, context?: TrackContext): Promise<void>;
```

### Parameters [#parameters-1]

* **`name`** (`string`, Required): The name of the event you want to track.
* **`properties`** (`object`, Optional): Additional key-value pairs related to the event.

### Example [#example-2]

```tsx
await rybbit.event("signup_started", { plan: "pro" });

await rybbit.event("purchase_completed", {
  orderId: "order-123",
  total: 49.99,
  currency: "USD",
});
```

## Error Tracking [#error-tracking]

Capture handled errors with additional context. Error tracking must be enabled in your Rybbit dashboard (Capture Errors) — when disabled, `error()` calls are ignored.

### Syntax [#syntax-3]

```typescript
rybbit.error(error: Error | unknown, properties?: TrackProperties, context?: TrackContext): Promise<void>;
```

Non-`Error` values are converted to an `Error`. The message is truncated to 500 characters and the stack trace to 2,000.

### Example [#example-3]

```tsx
try {
  await processPayment(order);
} catch (error) {
  await rybbit.error(error, { component: "checkout", orderId: order.id });
  showErrorMessage();
}
```

<Callout type="info">
  Unlike the web SDK, the React Native SDK does not automatically capture uncaught exceptions — wrap the code you care about and call `rybbit.error()` yourself.
</Callout>

## User Identification [#user-identification]

Associate events with a user ID and optional traits. The ID is persisted through the configured storage adapter and attached to all subsequent events.

```typescript
rybbit.identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
rybbit.setTraits(traits: Record<string, unknown>): Promise<void>;
rybbit.clearUserId(): Promise<void>;
rybbit.getUserId(): string | null;
```

```tsx
// After login
await rybbit.identify("user_123", { plan: "pro", signupDate: "2026-01-15" });

// Update traits later without changing the ID
await rybbit.setTraits({ plan: "enterprise" });

// After logout
await rybbit.clearUserId();
```

<Callout type="info">
  `setTraits()` throws if no user has been identified yet — call `identify()` first.
</Callout>

## App Lifecycle Events [#app-lifecycle-events]

With `autoTrackAppLifecycle` enabled (the default), the SDK listens to React Native's `AppState` and tracks:

* **`app_open`** — when the app launches in the foreground or returns to the foreground from the background.
* **`app_background`** — when the app leaves the foreground, with a `state` property (`"background"` or `"inactive"`).

Set `autoTrackAppLifecycle: false` in `init()` to disable these events.

## Offline Handling and Retries [#offline-handling-and-retries]

Events that fail to send (e.g., no network) are kept in an in-memory queue, capped at `maxQueueSize` (default 100, oldest dropped first). Queued events are retried when `init()` completes and whenever you call:

```typescript
rybbit.flush(): Promise<void>;
```

<Callout type="warning">
  The retry queue is in-memory only — events still queued when the app is killed are lost.
</Callout>

## Track Context [#track-context]

All tracking methods accept an optional `context` object to override what's sent with that event:

| Field           | Type     | Description                                   |
| :-------------- | :------- | :-------------------------------------------- |
| `appIdentifier` | `string` | Override the hostname for this event.         |
| `pathname`      | `string` | Override the tracked path.                    |
| `querystring`   | `string` | Query string to attach to the event.          |
| `screen`        | `string` | Screen name, used as the path/title fallback. |
| `title`         | `string` | Override the page title.                      |
| `referrer`      | `string` | Referrer value (empty by default on mobile).  |
| `language`      | `string` | Override the detected device locale.          |
| `userAgent`     | `string` | Override the synthetic user agent.            |

Device locale, screen dimensions, and a platform-appropriate user agent (including your `appVersion`) are detected automatically.

## Cleanup [#cleanup]

Removes the `AppState` lifecycle listener. Call it if you tear down the SDK, e.g. in tests or when unmounting your app root.

```typescript
rybbit.cleanup(): void;
```

## Differences from the Web SDK [#differences-from-the-web-sdk]

* **Session replay** and **Web Vitals** are web-only and not available for React Native apps.
* No automatic outbound link, button click, form, or copy tracking (there is no DOM).
* Uncaught errors are not captured automatically — use `rybbit.error()` in your own error boundaries and catch blocks.
* The anonymous visitor ID is generated by the SDK and persisted via your storage adapter, rather than derived from browser fingerprinting.


# JavaScript (Web) (/fr/docs/sdks/web)





## Installation [#installation]

```bash
npm install @rybbit/js
```

```bash
yarn add @rybbit/js
```

## Peer Dependencies [#peer-dependencies]

The SDK has an optional peer dependency for session replay functionality:

```bash
npm install rrweb
```

```bash
yarn add rrweb
```

<Callout type="info">
  The `rrweb` package is only required if you enable session replay in your Rybbit dashboard. The SDK will work without it for all other tracking features.
</Callout>

## Initialization [#initialization]

<Callout type="warning">
  `rybbit.init()` **must** be called once before any other tracking methods (`pageview`, `event`, etc.) can be used. Attempting to call other methods before `init` will result in errors or no tracking.
</Callout>

### Syntax [#syntax]

```typescript
async rybbit.init(config: RybbitConfig): Promise<void>;
```

### Example [#example]

```javascript
import rybbit from "@rybbit/js";

await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
});
```

### Configuration Options [#configuration-options]

#### Required Options [#required-options]

| Option          | Type     | Description                                                                        |
| :-------------- | :------- | :--------------------------------------------------------------------------------- |
| `analyticsHost` | `string` | URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |
| `siteId`        | `string` | The Site ID for your website obtained from your Rybbit instance.                   |

#### Local Configuration Options [#local-configuration-options]

These options are configured in your code and control SDK behavior locally:

| Option                | Type       | Default | Description                                                                                                                                                             |
| :-------------------- | :--------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `debounceDuration`    | `number`   | `500`   | Debounce time in milliseconds for tracking pageviews after route changes. Set to `0` to disable debouncing (track immediately).                                         |
| `skipPatterns`        | `string[]` | `[]`    | Array of path patterns. Pageviews whose path matches any pattern will **not** be tracked. See [Path Matching](#path-matching).                                          |
| `maskPatterns`        | `string[]` | `[]`    | Array of path patterns. For matching pageview paths, the original path will be **replaced** by the pattern itself in tracked data. See [Path Matching](#path-matching). |
| `debug`               | `boolean`  | `false` | Enable detailed logging to the browser console.                                                                                                                         |
| `replayPrivacyConfig` | `object`   | -       | Privacy settings for session replay. See [Session Replay](#session-replay).                                                                                             |

#### Remote Configuration [#remote-configuration]

These settings are controlled through your Rybbit dashboard and cannot be set in the init config:

| Dashboard Setting       | Description                                              | Default |
| :---------------------- | :------------------------------------------------------- | :------ |
| Track Initial Pageview  | Track pageview on initial page load                      | `true`  |
| Track SPA Navigation    | Track pageviews on Single Page Application route changes | `true`  |
| Track URL Parameters    | Include URL query strings in tracked data                | `true`  |
| Track Outbound Links    | Automatically track clicks on external links             | `true`  |
| Track Web Vitals        | Track Core Web Vitals performance metrics                | `false` |
| Capture Errors          | Enable automatic error tracking                          | `false` |
| Session Replay          | Enable session replay recording                          | `false` |
| Track Button Clicks     | Automatically track button click interactions            | `false` |
| Track Copy              | Automatically track copy events                          | `false` |
| Track Form Interactions | Automatically track form submissions and input changes   | `false` |

If fetching settings fails or times out, the SDK uses sensible defaults.

## Tracking Pageviews [#tracking-pageviews]

Pageviews are tracked automatically based on your dashboard settings. This includes the initial page load and subsequent route changes in Single Page Applications (SPAs).

### Syntax [#syntax-1]

```typescript
rybbit.pageview(path?: string);
```

### Parameters [#parameters]

* **`path`** (`string`, Optional):
  * Replaces the detected URL path (`window.location.pathname`) and query string (`window.location.search`) for this specific pageview event.
  * Should start with a `/` (e.g., `/virtual/my-custom-page`).
  * If `path` includes its own query string (e.g., `/virtual/step?id=123`), that query string will be used for the event. If `path` has no query string, the `querystring` property will be empty.
  * `skipPatterns` and `maskPatterns` will be applied to `path`.

### When to Use Manually [#when-to-use-manually]

* **Automatic tracking disabled:** If you disabled automatic pageview tracking in your dashboard.
* **Virtual Pageviews:** In SPAs where a significant view change occurs without a URL change.
* **Specific Timing:** If you need to ensure a pageview is tracked only after certain conditions are met.

### Example [#example-1]

```javascript
// Standard manual pageview (usually not needed if auto-tracking is on)
rybbit.pageview();

// Example: Track a step within a multi-step modal
function openUserDetailsModal(userId, step) {
  // ... logic to open and display the modal step ...
  rybbit.pageview(`/users/${userId}/modal/${step}`);
}
openUserDetailsModal("user-abc", "contact-info");

// Example: Track a virtual pageview with its own query parameters
function showFilteredProductList(category, sortBy) {
   let virtualPathWithQuery = `/products/category/${category}?sort=${sortBy}&view=grid`;
   rybbit.pageview(virtualPathWithQuery);
}
showFilteredProductList("electronics", "price_desc");
```

## Tracking Custom Events [#tracking-custom-events]

Use custom events to track specific user interactions. Examples include button clicks, form submissions, or adding an item to a cart.

### Programmatic Tracking [#programmatic-tracking]

You can trigger events from your JavaScript code.

#### Syntax [#syntax-2]

```typescript
rybbit.event(name: string, properties?: TrackProperties);
```

#### Parameters [#parameters-1]

* **`name`** (`string`, Required): The name of the event you want to track.
* **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values can be a `string`, `number`, `boolean`, or an array of these types.

#### Example [#example-2]

```javascript
// Track a simple button click
document.getElementById("cta-button")?.addEventListener("click", () => {
  rybbit.event("cta_click");
});

// Track adding an item to a shopping cart with properties
function addToCart(item) {
  // ... add item ...
  rybbit.event("add_to_cart", {
    itemId: item.id,
    itemName: item.name,
    price: item.price,
    quantity: 1
  });
}
```

### Declarative Tracking with Data Attributes [#declarative-tracking-with-data-attributes]

The SDK automatically listens for clicks on elements with the `data-rybbit-event` attribute.

* `data-rybbit-event="<event-name>"`: This attribute makes the element trackable. The value is used as the event name.
* `data-rybbit-prop-<property-name>="<value>"`: You can add multiple properties to the event by using this attribute format. The SDK collects all attributes starting with `data-rybbit-prop-` and includes them as key-value pairs in the event data.

#### Example [#example-3]

```html
<button data-rybbit-event="cta_click">Click Me</button>

<button
  data-rybbit-event="add_to_cart"
  data-rybbit-prop-item_id="product-123"
  data-rybbit-prop-item_name="Classic T-Shirt"
  data-rybbit-prop-price="29.99"
>
  Add to Cart
</button>
```

## Tracking Outbound Links [#tracking-outbound-links]

Outbound links (links to external domains) are tracked automatically by default based on your dashboard settings. The SDK attaches a global click listener to capture clicks on `<a>` tags with external `href` attributes.

### Syntax [#syntax-3]

```typescript
rybbit.trackOutbound(url: string, text?: string, target?: string);
```

### Parameters [#parameters-2]

* **`url`** (`string`, Required): The destination URL of the outbound link.
* **`text`** (`string`, Optional): The text content of the link. Defaults to `""`.
* **`target`** (`string`, Optional): The `target` attribute of the link (e.g., `_blank`). Defaults to `_self`.

### When to Use Manually [#when-to-use-manually-1]

* **Automatic tracking disabled:** If you disabled outbound link tracking in your dashboard.
* **Non-anchor elements:** If you trigger navigation to an external site using JavaScript from an element that isn't an `<a>` tag.

### Example [#example-4]

```javascript
// Manually track an outbound click triggered by a button
document.getElementById("external-service-button")?.addEventListener("click", () => {
  let url = "https://external-service.com";
  rybbit.trackOutbound(url, "Visit External Service", "_blank");
  // Optionally navigate after tracking
  window.open(url, "_blank");
});
```

## Error Tracking [#error-tracking]

The SDK can automatically capture JavaScript errors and unhandled promise rejections. This feature must be enabled in your Rybbit dashboard.

### Automatic Error Capture [#automatic-error-capture]

When enabled in your dashboard, the SDK will automatically track:

* Uncaught exceptions (`window.error` events)
* Unhandled promise rejections (`window.unhandledrejection` events)

### Manual Error Capture [#manual-error-capture]

You can manually capture errors with additional context:

#### Syntax [#syntax-4]

```typescript
rybbit.error(error: Error | ErrorEvent, context?: TrackProperties);
```

#### Parameters [#parameters-3]

* **`error`** (`Error | ErrorEvent`, Required): The error object to capture.
* **`context`** (`object`, Optional): Additional context to include with the error.

#### Example [#example-5]

```javascript
try {
  // Some risky operation
  processPayment(orderData);
} catch (error) {
  rybbit.error(error, {
    component: "checkout",
    orderId: "order-123",
    userId: currentUser.id
  });
  // Handle error in your UI
  showErrorMessage("Payment failed");
}

// Capture error from async operation
async function fetchUserData(userId) {
  try {
    const response = await fetch(`/api/users/${userId}`);
    return await response.json();
  } catch (error) {
    rybbit.error(error, {
      endpoint: "/api/users",
      userId: userId
    });
    throw error;
  }
}
```

<Callout type="info">
  Manual error capture only works when error tracking is enabled in your dashboard settings. If it's disabled, calling `error()` will log a warning.
</Callout>

## Session Replay [#session-replay]

Session replay records user interactions on your website, allowing you to watch how users navigate and interact with your site. This feature requires the `rrweb` peer dependency.

### Installation [#installation-1]

```bash
npm install rrweb
```

### Enabling Session Replay [#enabling-session-replay]

Session replay must be enabled in your Rybbit dashboard under. Once enabled, recording starts automatically when the SDK initializes.

### Manual Controls [#manual-controls]

You can manually start, stop, and check the status of session replay:

```typescript
// Start recording (only works if enabled in dashboard)
rybbit.startSessionReplay();

// Stop recording
rybbit.stopSessionReplay();

// Check if currently recording
const isRecording = rybbit.isSessionReplayActive();
if (isRecording) {
  console.log("Session is being recorded");
}
```

### Privacy Configuration [#privacy-configuration]

Session replay includes privacy-focused defaults and configuration options:

```javascript
await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  replayPrivacyConfig: {
    maskAllInputs: true, // Mask all input values (default: true)
    maskTextSelectors: [
      ".sensitive-data",  // Mask text in elements with this class
      "#credit-card"      // Mask specific element IDs
    ]
  }
});
```

#### Privacy Config Options [#privacy-config-options]

| Option              | Type                | Description                                                             |
| :------------------ | :------------------ | :---------------------------------------------------------------------- |
| `maskAllInputs`     | `boolean`           | Mask all input values (default: `true`)                                 |
| `maskTextSelectors` | `string[]`          | CSS selectors for elements whose text should be masked                  |
| `blockClass`        | `string`            | CSS class name to block elements from recording (default: `rr-block`)   |
| `blockSelector`     | `string`            | CSS selector to block elements from recording                           |
| `ignoreClass`       | `string`            | CSS class name to ignore elements from recording (default: `rr-ignore`) |
| `ignoreSelector`    | `string`            | CSS selector to ignore elements from recording                          |
| `maskTextClass`     | `string`            | CSS class name to mask text content (default: `rr-mask`)                |
| `collectFonts`      | `boolean`           | Whether to collect font information (default: `true`)                   |
| `slimDOMOptions`    | `object \| boolean` | Options to reduce DOM snapshot size                                     |

## User Identification [#user-identification]

You can associate tracking events with a specific user ID and optional traits. The ID is persisted in `localStorage` and will be attached to all subsequent tracking events for that user.

### `identify` [#identify]

Assigns a user ID with optional traits.

```typescript
rybbit.identify(userId: string, traits?: Record<string, unknown>);
```

**Parameters:**

* **`userId`** (`string`, Required): The user ID to associate with tracking events.
* **`traits`** (`object`, Optional): An object containing user attributes/properties.

**Example:**

```javascript
// After a user logs in
rybbit.identify("user-xzy-123");

// With traits
rybbit.identify("user-xzy-123", {
  email: "user@example.com",
  plan: "premium",
  signupDate: "2024-01-15"
});
```

### `setTraits` [#settraits]

Updates traits for the currently identified user without changing the user ID.

```typescript
rybbit.setTraits(traits: Record<string, unknown>);
```

**Example:**

```javascript
// Update user traits after they upgrade
rybbit.setTraits({
  plan: "enterprise",
  upgradeDate: "2024-03-01"
});
```

### `clearUserId` [#clearuserid]

Clears the stored user ID.

```typescript
rybbit.clearUserId();
```

**Example:**

```javascript
// When a user logs out
rybbit.clearUserId();
```

### `getUserId` [#getuserid]

Retrieves the currently stored user ID.

```typescript
rybbit.getUserId(): string | null;
```

**Example:**

```javascript
let currentUserId = rybbit.getUserId();
console.log("Current Rybbit User ID:", currentUserId);
```

## Page Change Callbacks [#page-change-callbacks]

Register callbacks that execute when the page or route changes. This is useful for integrating with third-party tools or triggering custom logic on navigation.

### Syntax [#syntax-5]

```typescript
rybbit.onPageChange(callback: (newPath: string, previousPath: string) => void): () => void;
```

### Parameters [#parameters-4]

* **`callback`** (`function`, Required): Function to execute on page change. Receives:
  * `newPath`: The new pathname
  * `previousPath`: The previous pathname

### Returns [#returns]

Returns an unsubscribe function to remove the callback.

### Example [#example-6]

```javascript
// Register a callback
const unsubscribe = rybbit.onPageChange((newPath, previousPath) => {
  console.log(`Navigated from ${previousPath} to ${newPath}`);

  // Example: Track scroll position reset
  window.scrollTo(0, 0);
});

// Later, to remove the callback
unsubscribe();

// Example: Multiple callbacks can be registered
rybbit.onPageChange((newPath) => {
  // Update page title
  document.title = `${newPath} - My Site`;
});

rybbit.onPageChange((newPath, previousPath) => {
  // Log navigation for debugging
  if (process.env.NODE_ENV === 'development') {
    console.log('Navigation:', { from: previousPath, to: newPath });
  }
});
```

<Callout type="info">
  Callbacks are only triggered when the pathname actually changes. Multiple calls to the same path won't trigger callbacks repeatedly.
</Callout>

## Opting Out [#opting-out]

Users can opt out of all tracking by setting a flag in `localStorage` or on the `window` object. When opted out, all tracking calls are silently ignored.

```javascript
// Opt out via localStorage (persists across sessions)
localStorage.setItem("disable-rybbit", "true");

// Opt out via window flag (current session only)
window.__RYBBIT_OPTOUT__ = true;
```

To re-enable tracking, remove the localStorage item and reload the page:

```javascript
localStorage.removeItem("disable-rybbit");
```

## Cleanup [#cleanup]

In Single Page Applications or other dynamic environments, you may need to manually clean up the listeners that the SDK sets up.

### Syntax [#syntax-6]

```typescript
rybbit.cleanup();
```

### What Gets Cleaned Up [#what-gets-cleaned-up]

* SPA route change listeners (`popstate`, `hashchange`)
* Outbound link click listeners
* Data attribute click listeners
* Error tracking listeners
* Session replay recording
* Page change callbacks
* Resets initialization state

### Example [#example-7]

```javascript
// In React
useEffect(() => {
  rybbit.init({
    analyticsHost: "https://app.rybbit.io/api",
    siteId: "1",
  });

  return () => {
    rybbit.cleanup();
  };
}, []);
```

## Path Matching [#path-matching]

These options allow you to control which page paths are tracked and how they appear in your analytics data using wildcard patterns.

### Wildcards [#wildcards]

* `*`: Matches any sequence of characters **except** the forward slash (`/`). Useful for matching single path segments.
* `**`: Matches any sequence of characters **including** the forward slash (`/`). Useful for matching multiple path segments.

### Regex Patterns [#regex-patterns]

For more advanced matching, you can use raw regular expressions by prefixing the pattern with `re:`:

```javascript
skipPatterns: [
  "re:^/users/\\d+/profile$",  // Match numeric user IDs only
  "re:^/api/v[0-9]+/"          // Match any API version prefix
]
```

### `skipPatterns` [#skippatterns]

If a page's path matches any pattern in `skipPatterns`, the pageview for that path will **not** be sent.

**Examples:**

* `"/admin/*"`: Skips `/admin/login`, `/admin/users`, but **not** `/admin/settings/profile`.
* `"/admin/**"`: Skips `/admin/login`, `/admin/users`, *and* `/admin/settings/profile`.
* `"/users/*/profile"`: Skips `/users/123/profile`, `/users/abc/profile`, but **not** `/users/123/settings`.

```javascript
// Example skipPatterns in init
await rybbit.init({
  // ... other options
  skipPatterns: [
    "/admin/**",        // Skip all admin sections
    "/debug",           // Skip exact /debug path
    "/users/*/settings" // Skip settings page for any user
  ]
});
```

### `maskPatterns` [#maskpatterns]

If a page's path matches a pattern in `maskPatterns`, the pageview **will** be sent, but the `pathname` will be **replaced** by the pattern string itself. This is useful for grouping similar pages or hiding sensitive IDs.

<Callout type="warning">
  If a path matches both a `skipPatterns` and a `maskPatterns` pattern, **skipping takes priority**.
</Callout>

**Examples:**

* Pattern: `"/users/*/profile"`
  * `/users/123/profile` is tracked as `pathname: "/users/*/profile"`.
* Pattern: `"/products/**"`
  * `/products/electronics/tv-123` is tracked as `pathname: "/products/**"`.

```javascript
// Example maskPatterns in init
await rybbit.init({
  // ... other options
  maskPatterns: [
    "/users/*/profile",  // Group all user profile views
    "/orders/*"          // Mask specific order IDs
  ]
});
```


# Custom Nginx setup (/fr/docs/self-hosting-guides/custom-nginx)





This guide shows you how to set up Rybbit with your own Nginx installation instead of using the built-in Caddy server.

## Prerequisites [#prerequisites]

* Existing Nginx installation
* SSL certificates (Let's Encrypt recommended)
* Domain pointed to your server
* Rybbit running with `--no-webserver` flag

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Run Rybbit without Caddy [#run-rybbit-without-caddy]

    First, set up Rybbit to expose ports without the built-in webserver:

    ```bash
    ./setup.sh your.domain.name --no-webserver
    ```

    Optionally, include a Mapbox token for globe visualizations:

    ```bash
    ./setup.sh your.domain.name --no-webserver --mapbox-token YOUR_MAPBOX_TOKEN
    ```

    This will expose:

    * Backend service on port 3001
    * Client service on port 3002
  </Step>

  <Step>
    ### Configure Nginx [#configure-nginx]

    Create or update your Nginx configuration file (usually in `/etc/nginx/sites-available/`):

    ```nginx
    server {
        listen 80;
        server_name your.domain.name;
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name your.domain.name;

        # SSL configuration (using Let's Encrypt)
        ssl_certificate /etc/letsencrypt/live/your.domain.name/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/your.domain.name/privkey.pem;
        
        # Modern SSL configuration
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
        ssl_prefer_server_ciphers off;
        
        # Security headers
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-XSS-Protection "1; mode=block" always;

        # Backend service
        location ~ ^/(api|\.well-known)/.*$ {
            proxy_pass http://localhost:3001;
            proxy_set_header Host $host;
            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_set_header X-Forwarded-Host $server_name;
            
            # Timeouts
            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
        }

        # Client service
        location / {
            proxy_pass http://localhost:3002;
            proxy_set_header Host $host;
            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_set_header X-Forwarded-Host $server_name;
            
            # Timeouts
            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
        }
    }
    ```
  </Step>

  <Step>
    ### Enable the Site [#enable-the-site]

    Enable your Nginx configuration:

    ```bash
    # Create symlink to enable the site
    sudo ln -s /etc/nginx/sites-available/your-site /etc/nginx/sites-enabled/

    # Test the configuration
    sudo nginx -t

    # Reload Nginx
    sudo systemctl reload nginx
    ```
  </Step>

  <Step>
    ### Verify Setup [#verify-setup]

    Check that everything is working:

    ```bash
    # Check Nginx status
    sudo systemctl status nginx

    # Check Rybbit services
    docker compose ps

    # Test the website
    curl -I https://your.domain.name
    ```
  </Step>
</Steps>

## SSL Certificate Setup with Certbot [#ssl-certificate-setup-with-certbot]

If you need to set up SSL certificates with Let's Encrypt:

<Steps>
  <Step>
    ### Install Certbot [#install-certbot]

    ```bash
    # Ubuntu/Debian
    sudo apt update
    sudo apt install certbot python3-certbot-nginx

    # CentOS/RHEL
    sudo yum install certbot python3-certbot-nginx
    ```
  </Step>

  <Step>
    ### Obtain Certificate [#obtain-certificate]

    ```bash
    sudo certbot --nginx -d your.domain.name
    ```
  </Step>

  <Step>
    ### Auto-renewal [#auto-renewal]

    Set up automatic renewal:

    ```bash
    # Test renewal
    sudo certbot renew --dry-run

    # Check existing cron job
    sudo crontab -l
    ```

    Certbot usually sets up auto-renewal automatically, but you can add this cron job if needed:

    ```bash
    0 12 * * * /usr/bin/certbot renew --quiet
    ```
  </Step>
</Steps>

## Custom Ports [#custom-ports]

If you need to use custom ports for Rybbit:

```bash
./setup.sh your.domain.name --no-webserver --backend-port 8080 --client-port 8081

# With Mapbox token
./setup.sh your.domain.name --no-webserver --backend-port 8080 --client-port 8081 --mapbox-token YOUR_MAPBOX_TOKEN
```

Update your Nginx configuration accordingly:

```nginx
location /api/ {
    proxy_pass http://localhost:8080;  # Custom backend port
    # ... rest of config
}

location / {
    proxy_pass http://localhost:8081;  # Custom client port
    # ... rest of config
}
```

## Troubleshooting [#troubleshooting]

### Common Issues [#common-issues]

**502 Bad Gateway**: Check if Rybbit services are running:

```bash
docker compose ps
docker compose logs
```

**SSL Certificate Issues**: Verify certificate paths:

```bash
sudo certbot certificates
```

**Permission Denied**: Check Nginx error logs:

```bash
sudo tail -f /var/log/nginx/error.log
```

### Logs [#logs]

Monitor logs for debugging:

```bash
# Nginx access logs
sudo tail -f /var/log/nginx/access.log

# Nginx error logs
sudo tail -f /var/log/nginx/error.log

# Rybbit logs
docker compose logs -f
```


# Nginx Proxy Manager (NPM) setup (/fr/docs/self-hosting-guides/nginx-proxy-manager)





This guide shows you how to set up Rybbit with Nginx Proxy Manager without exposing ports directly to the host.

## Prerequisites [#prerequisites]

* [Nginx Proxy Manager](https://nginxproxymanager.com) already running
* Basic knowledge of Docker networks
* Domain name pointed to your server

<Callout type="info">
  This setup assumes you have NPM running and are capable of creating SSL certificates. You can also use any other reverse proxy as long as you can put it on the same Docker network as Rybbit.
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Create Custom Docker Compose [#create-custom-docker-compose]

    Create a new directory for your Rybbit installation and create a `docker-compose.yml` file:

    ```yaml
    services:
      rybbit_clickhouse:
        image: clickhouse/clickhouse-server:26.3.17.4
        container_name: rybbit_clickhouse
        volumes:
          - ./clickhouse-data:/var/lib/clickhouse
        configs:
          - source: clickhouse_network
            target: /etc/clickhouse-server/config.d/network.xml
          - source: clickhouse_logging
            target: /etc/clickhouse-server/config.d/logging_rules.xml
          # Profile (user-level) settings are only read from users.d, not config.d
          - source: clickhouse_user_settings
            target: /etc/clickhouse-server/users.d/user_settings.xml
        environment:
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        networks:
          - internal

      rybbit_postgres:
        image: postgres:17.4
        container_name: rybbit_postgres
        environment:
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
        volumes:
          - ./postgres-data:/var/lib/postgresql/data
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        networks:
          - internal

      rybbit_redis:
        image: redis:8.6.4-alpine
        container_name: rybbit_redis
        volumes:
          - ./redis-data:/data
        healthcheck:
          test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 5s
        restart: unless-stopped
        command:
          - redis-server
          - --requirepass
          - ${REDIS_PASSWORD:-changeme}
          - --appendonly
          - "yes"
          - --appendfsync
          - everysec
          - --maxmemory-policy
          - noeviction
        networks:
          - internal

      rybbit_backend:
        image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}
        container_name: rybbit_backend
        environment:
          - NODE_ENV=production
          - CLICKHOUSE_HOST=http://rybbit_clickhouse:8123
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
          - POSTGRES_HOST=rybbit_postgres
          - POSTGRES_PORT=5432
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - REDIS_HOST=rybbit_redis
          - REDIS_PORT=6379
          - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
          - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
          - BASE_URL=${BASE_URL}
          - DISABLE_SIGNUP=${DISABLE_SIGNUP}
          - MAPBOX_TOKEN=${MAPBOX_TOKEN}
        depends_on:
          rybbit_clickhouse:
            condition: service_healthy
          rybbit_postgres:
            condition: service_healthy
          rybbit_redis:
            condition: service_healthy
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3001/api/health"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        networks:
          - internal
          - npm_proxy

      rybbit_client:
        image: ghcr.io/rybbit-io/rybbit-client:${IMAGE_TAG:-latest}
        container_name: rybbit_client
        environment:
          - NODE_ENV=production
          - NEXT_PUBLIC_BACKEND_URL=${BASE_URL}
          - NEXT_PUBLIC_DISABLE_SIGNUP=${DISABLE_SIGNUP}
        depends_on:
          - rybbit_backend
        restart: unless-stopped
        networks:
          - internal
          - npm_proxy

    networks:
      internal:
        driver: bridge
      npm_proxy:
        external: true

    configs:
      clickhouse_network:
        content: |
          <clickhouse>
              <listen_host>0.0.0.0</listen_host>
          </clickhouse>

      clickhouse_logging:
        content: |
          <clickhouse>
            <logger>
                <level>warning</level>
                <console>true</console>
            </logger>
            <query_thread_log remove="remove"/>
            <query_log remove="remove"/>
            <text_log remove="remove"/>
            <trace_log remove="remove"/>
            <metric_log remove="remove"/>
            <asynchronous_metric_log remove="remove"/>
            <session_log remove="remove"/>
            <part_log remove="remove"/>
            <latency_log remove="remove"/>
            <processors_profile_log remove="remove"/>
          </clickhouse>

      clickhouse_user_settings:
        content: |
          <clickhouse>
            <profiles>
              <default>
                <enable_json_type>1</enable_json_type>
                <!-- 26.3+ enables async_insert by default; the backend already
                     batches app-side, so keep inserts synchronous -->
                <async_insert>0</async_insert>
                <log_queries>0</log_queries>
                <log_query_threads>0</log_query_threads>
                <log_processors_profiles>0</log_processors_profiles>
              </default>
            </profiles>
          </clickhouse>
    ```
  </Step>

  <Step>
    ### Configure Environment [#configure-environment]

    Create a `.env` file in the same directory:

    ```bash
    # Required: Your domain and base URL
    DOMAIN_NAME=your.domain.com
    BASE_URL=https://your.domain.com

    # Required: Authentication secret (generate a random 32+ character string)
    BETTER_AUTH_SECRET=your_generated_secret_here

    # Optional: Disable new user signups after creating admin account
    DISABLE_SIGNUP=false

    # Optional but recommended: Mapbox token for globe visualizations
    MAPBOX_TOKEN=your_mapbox_token

    # Optional: Custom image tag
    IMAGE_TAG=latest
    ```

    <Callout type="info">
      Generate a secure `BETTER_AUTH_SECRET` using: `openssl rand -hex 32`
    </Callout>
  </Step>

  <Step>
    ### Setup Docker Network [#setup-docker-network]

    Create the external network that NPM uses (if it doesn't exist):

    ```bash
    docker network create npm_proxy
    ```

    Make sure your NPM container is connected to this network:

    ```bash
    # Check if NPM is on the network
    docker network inspect npm_proxy

    # If needed, connect NPM to the network
    docker network connect npm_proxy <npm_container_name>
    ```
  </Step>

  <Step>
    ### Start Services [#start-services]

    Start all Rybbit services:

    ```bash
    docker compose up -d
    ```

    Verify all services are running:

    ```bash
    docker compose ps
    ```
  </Step>

  <Step>
    ### Configure NPM [#configure-npm]

    In your Nginx Proxy Manager interface:

    1. **Create Proxy Host**:
       * Domain Names: `your.domain.com`
       * Scheme: `http`
       * Forward Hostname/IP: `rybbit_client`
       * Forward Port: `3002`
       * Enable "Cache Assets", "Block Common Exploits", "Websockets Support"

    2. **Add Custom Location**:
       * Location: `/api`
       * Scheme: `http`
       * Forward Hostname/IP: `rybbit_backend`
       * Forward Port: `3001`

    3. **Advanced Configuration** (in the custom location):
       ```nginx
       location /api/ {
           proxy_pass http://rybbit_backend:3001;
           proxy_set_header Host $host;
           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;
       }
       ```

    4. **SSL Configuration**:
       * Enable SSL
       * Request a new SSL certificate with Let's Encrypt
       * Enable "Force SSL" and "HTTP/2 Support"
  </Step>

  <Step>
    ### Access Rybbit [#access-rybbit]

    Navigate to `https://your.domain.com` and create your admin account.
  </Step>
</Steps>

## Alternative Proxy Configurations [#alternative-proxy-configurations]

### Traefik [#traefik]

If you're using Traefik instead, add these labels to your services:

```yaml
services:
  rybbit_backend:
    # ... existing config
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && PathPrefix(`/api`)"
      - "traefik.http.routers.rybbit-api.tls.certresolver=letsencrypt"
      - "traefik.http.services.rybbit-api.loadbalancer.server.port=3001"
      - "traefik.docker.network=traefik_proxy"
  
  rybbit_client:
    # ... existing config
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.rybbit-client.rule=Host(`your.domain.com`)"
      - "traefik.http.routers.rybbit-client.tls.certresolver=letsencrypt"
      - "traefik.http.services.rybbit-client.loadbalancer.server.port=3002"
      - "traefik.docker.network=traefik_proxy"

networks:
  traefik_proxy:
    external: true
```

### Cloudflare Tunnel [#cloudflare-tunnel]

For Cloudflare Tunnel, create a tunnel configuration:

```yaml
tunnel: your-tunnel-id
credentials-file: /path/to/credentials.json

ingress:
  - hostname: your.domain.com
    path: /api
    service: http://rybbit_backend:3001
  - hostname: your.domain.com
    service: http://rybbit_client:3002
  - service: http_status:404
```

## Troubleshooting [#troubleshooting]

### Common Issues [#common-issues]

**NPM can't reach containers**:

* Verify both NPM and Rybbit are on the same network
* Check container names match the proxy configuration

**SSL certificate issues**:

* Ensure domain is pointed to your server
* Check NPM logs for certificate generation errors

**502 Bad Gateway**:

* Verify Rybbit services are healthy: `docker compose ps`
* Check container logs: `docker compose logs`

### Networking [#networking]

Check network connectivity:

```bash
# List all networks
docker network ls

# Inspect the npm_proxy network
docker network inspect npm_proxy

# Check which containers are connected
docker ps --format "table {{.Names}}\t{{.Networks}}"
```

### Logs [#logs]

Monitor logs for debugging:

```bash
# Rybbit services
docker compose logs -f

# Specific service
docker compose logs -f rybbit_backend

# NPM logs (adjust container name)
docker logs -f nginx-proxy-manager
```

<Callout type="warning">
  Remember to regularly backup your data volumes (`clickhouse-data` and `postgres-data`) and your `.env` file.
</Callout>


# Pangolin setup (/fr/docs/self-hosting-guides/pangolin)







This guide shows you how to set up Rybbit with [Pangolin](https://github.com/fosrl/pangolin), a self-hosted reverse proxy, using a Newt container inside the Docker Compose stack. This approach avoids exposing ports directly on your host network.

## Prerequisites [#prerequisites]

* [Pangolin](https://github.com/fosrl/pangolin) already running and accessible (e.g. `https://pangolin.yourdomain.com`)
* A Newt ID and Newt Secret from your Pangolin instance
* A domain name pointed to your Pangolin server (e.g. `tracking.yourdomain.com`)
* Docker and Docker Compose installed

<Callout type="warning">
  You **must** generate a proper `BETTER_AUTH_SECRET` before starting. Without a valid 32+ character secret, you will not be able to create organizations or log in. Generate one with: `openssl rand -hex 32`
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Configure Environment Variables [#configure-environment-variables]

    Create a `.env` file in your Rybbit directory:

    ```bash
    # Required: Your domain and base URL
    DOMAIN_NAME=tracking.yourdomain.com
    BASE_URL=https://tracking.yourdomain.com

    # Required: Authentication secret (must be 32+ characters)
    # Generate with: openssl rand -hex 32
    BETTER_AUTH_SECRET=your_generated_secret_here

    # Required: Disable built-in webserver since Pangolin handles routing
    USE_WEBSERVER=false

    # ClickHouse configuration
    CLICKHOUSE_DB=analytics
    CLICKHOUSE_USER=default
    CLICKHOUSE_PASSWORD=changeme

    # PostgreSQL configuration
    POSTGRES_DB=analytics
    POSTGRES_USER=changeme
    POSTGRES_PASSWORD=changeme

    # Redis configuration
    REDIS_PASSWORD=changeme

    # Ports in host:container format (Pangolin needs it like this)
    HOST_BACKEND_PORT=3001:3001
    HOST_CLIENT_PORT=3002:3002

    # Optional: Disable new user signups after creating admin account
    # DISABLE_SIGNUP=true

    # Optional: Mapbox token for globe visualizations
    # MAPBOX_TOKEN=your_mapbox_token
    ```

    <Callout type="info">
      The `HOST_BACKEND_PORT` and `HOST_CLIENT_PORT` values use the `host:container` format without binding to `127.0.0.1`. This is intentional — the Newt container inside the Docker network handles routing, so the ports do not need to be exposed to your host. Even if you already run services on ports 3001/3002 on your host, there will be no conflict.
    </Callout>
  </Step>

  <Step>
    ### Create Docker Compose File [#create-docker-compose-file]

    Create a `docker-compose.yml` file in the same directory. This includes a Newt container that connects Pangolin to your Rybbit services:

    ```yaml
    services:
      newt:
        image: fosrl/newt
        container_name: newt-rybbit
        restart: unless-stopped
        environment:
          - PANGOLIN_ENDPOINT=https://pangolin.yourdomain.com
          - NEWT_ID=your_newt_id
          - NEWT_SECRET=your_newt_secret

      clickhouse:
        container_name: clickhouse
        image: clickhouse/clickhouse-server:26.3.17.4
        volumes:
          - clickhouse-data:/var/lib/clickhouse
        configs:
          - source: clickhouse_network
            target: /etc/clickhouse-server/config.d/network.xml
          - source: clickhouse_logging
            target: /etc/clickhouse-server/config.d/logging_rules.xml
          # Profile (user-level) settings are only read from users.d, not config.d
          - source: clickhouse_user_settings
            target: /etc/clickhouse-server/users.d/user_settings.xml
        environment:
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        ports:
          - "8123:8123"

      postgres:
        image: postgres:17.4
        container_name: postgres
        environment:
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
        volumes:
          - postgres-data:/var/lib/postgresql/data
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped
        ports:
          - "5432:5432"

      redis:
        image: redis:8.6.4-alpine
        container_name: redis
        volumes:
          - redis-data:/data
        healthcheck:
          test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 5s
        restart: unless-stopped
        command:
          - redis-server
          - --requirepass
          - ${REDIS_PASSWORD:-changeme}
          - --appendonly
          - "yes"
          - --appendfsync
          - everysec
          - --maxmemory-policy
          - noeviction

      backend:
        image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}
        container_name: backend
        ports:
          - "${HOST_BACKEND_PORT:-127.0.0.1:3001:3001}"
        environment:
          - NODE_ENV=production
          - CLICKHOUSE_HOST=http://clickhouse:8123
          - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
          - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
          - POSTGRES_HOST=postgres
          - POSTGRES_PORT=5432
          - POSTGRES_DB=${POSTGRES_DB:-analytics}
          - POSTGRES_USER=${POSTGRES_USER:-frog}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
          - REDIS_HOST=redis
          - REDIS_PORT=6379
          - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
          - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
          - BASE_URL=${BASE_URL}
          - DISABLE_SIGNUP=${DISABLE_SIGNUP}
          - DISABLE_TELEMETRY=${DISABLE_TELEMETRY}
          - MAPBOX_TOKEN=${MAPBOX_TOKEN}
        depends_on:
          clickhouse:
            condition: service_healthy
          postgres:
            condition: service_started
          redis:
            condition: service_healthy
        healthcheck:
          test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3001/api/health"]
          interval: 3s
          timeout: 5s
          retries: 5
          start_period: 10s
        restart: unless-stopped

      client:
        image: ghcr.io/rybbit-io/rybbit-client:${IMAGE_TAG:-latest}
        container_name: client
        ports:
          - "${HOST_CLIENT_PORT:-127.0.0.1:3002:3002}"
        environment:
          - NODE_ENV=production
          - NEXT_PUBLIC_BACKEND_URL=${BASE_URL}
          - NEXT_PUBLIC_DISABLE_SIGNUP=${DISABLE_SIGNUP}
        depends_on:
          - backend
        restart: unless-stopped

    volumes:
      clickhouse-data:
      postgres-data:
      redis-data:

    configs:
      clickhouse_network:
        content: |
          <clickhouse>
              <listen_host>0.0.0.0</listen_host>
          </clickhouse>

      clickhouse_logging:
        content: |
          <clickhouse>
            <logger>
                <level>warning</level>
                <console>true</console>
            </logger>
            <query_thread_log remove="remove"/>
            <query_log remove="remove"/>
            <text_log remove="remove"/>
            <trace_log remove="remove"/>
            <metric_log remove="remove"/>
            <asynchronous_metric_log remove="remove"/>
            <session_log remove="remove"/>
            <part_log remove="remove"/>
            <latency_log remove="remove"/>
            <processors_profile_log remove="remove"/>
          </clickhouse>

      clickhouse_user_settings:
        content: |
          <clickhouse>
            <profiles>
              <default>
                <enable_json_type>1</enable_json_type>
                <!-- 26.3+ enables async_insert by default; the backend already
                     batches app-side, so keep inserts synchronous -->
                <async_insert>0</async_insert>
                <log_queries>0</log_queries>
                <log_query_threads>0</log_query_threads>
                <log_processors_profiles>0</log_processors_profiles>
              </default>
            </profiles>
          </clickhouse>
    ```

    <Callout type="info">
      The `newt` service runs inside the same Docker network as your other containers. It connects to your Pangolin instance and routes traffic to `backend` and `client` by their container hostnames — no host port exposure needed for Pangolin to reach them.
    </Callout>
  </Step>

  <Step>
    ### Start Services [#start-services]

    Start all services:

    ```bash
    docker compose up -d
    ```

    Verify everything is running:

    ```bash
    docker compose ps
    ```

    Check that the backend is healthy:

    ```bash
    docker compose logs backend
    ```
  </Step>

  <Step>
    ### Configure Pangolin [#configure-pangolin]

    In your Pangolin dashboard, create a new site for your Rybbit domain and configure two resources:

    1. **Client resource** — routes the root domain to the Rybbit frontend:
       * Target: `client` (the Docker container hostname)
       * Port: `3002`

    2. **Backend resource** — routes `/api` traffic to the Rybbit backend:
       * Target: `backend` (the Docker container hostname)
       * Port: `3001`

    For both resources, add these custom headers in the Pangolin configuration:

    | Header              | Value                     |
    | ------------------- | ------------------------- |
    | `X-Forwarded-Proto` | `https`                   |
    | `X-Forwarded-Host`  | `tracking.yourdomain.com` |

        <img alt="Pangolin dashboard configuration" src="__img0" />

    <Callout type="warning">
      The `X-Forwarded-Proto` and `X-Forwarded-Host` headers are critical. Without them, API requests from the client to the backend will fail. This is the most common source of issues with this setup.
    </Callout>

    <Callout type="info">
      You do **not** need to enable "Advanced Mode" in Pangolin. The standard configuration with the correct headers is sufficient.
    </Callout>
  </Step>

  <Step>
    ### Access Rybbit [#access-rybbit]

    Navigate to `https://tracking.yourdomain.com` and create your admin account.

    If you see 404 errors on `/api` routes, double-check that:

    * Your `BETTER_AUTH_SECRET` is set and is at least 32 characters
    * The `X-Forwarded-Proto` and `X-Forwarded-Host` headers are configured in Pangolin
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

### Cannot create organizations or log in [#cannot-create-organizations-or-log-in]

This is almost always caused by a missing or invalid `BETTER_AUTH_SECRET`. Generate a proper secret:

```bash
openssl rand -hex 32
```

Add it to your `.env` file and restart the services:

```bash
docker compose down && docker compose up -d
```

### 404 errors on API routes [#404-errors-on-api-routes]

Verify that Pangolin is forwarding the correct headers. The `X-Forwarded-Proto` header must be `https` and `X-Forwarded-Host` must match your domain. Without these, the backend cannot properly handle requests.

### Backend health check failing [#backend-health-check-failing]

Check the backend logs for errors:

```bash
docker compose logs -f backend
```

Ensure ClickHouse and PostgreSQL are healthy:

```bash
docker compose ps
```

### Newt not connecting to Pangolin [#newt-not-connecting-to-pangolin]

Verify your Newt credentials and Pangolin endpoint:

```bash
docker compose logs -f newt-rybbit
```

Make sure `PANGOLIN_ENDPOINT`, `NEWT_ID`, and `NEWT_SECRET` are correct in your `docker-compose.yml`.

## Video Reference [#video-reference]

For a visual walkthrough of setting up Rybbit with Pangolin, see the official Pangolin YouTube guide:

<iframe width="560" height="315" src="https://www.youtube.com/embed/zk-ZhkNdyC8?start=5" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />


# Advanced self-hosting (/fr/docs/self-hosting-guides/self-hosting-advanced)





This guide covers advanced configuration options for self-hosting Rybbit.

## Setup Script Options [#setup-script-options]

The setup script supports several options:

```bash
./setup.sh <domain_name> [options]
```

Available options:

* `--no-webserver`: Disable the built-in Caddy webserver
* `--backend-port <port>`: Set custom host port for backend (default: 3001)
* `--client-port <port>`: Set custom host port for client (default: 3002)
* `--mapbox-token <token>`: Set Mapbox API token (optional but recommended for globe visualizations)
* `--help`: Show help message

Examples:

```bash
# With Mapbox token
./setup.sh tracking.example.com --mapbox-token YOUR_MAPBOX_TOKEN

# Custom ports with built-in webserver
./setup.sh tracking.example.com --backend-port 8080 --client-port 8081

# Custom ports with your own webserver
./setup.sh tracking.example.com --no-webserver --backend-port 8080 --client-port 8081
```

<Callout type="info">
  When you specify custom ports, only the host port mapping changes. Inside the Docker containers, the services still use ports 3001 and 3002.
</Callout>

## Using Your Own Web Server [#using-your-own-web-server]

If you prefer to use your own web server instead of the built-in Caddy server, you can use the `--no-webserver` flag:

```bash
./setup.sh your.domain.name --no-webserver
```

This will:

* Not start the Caddy container
* Expose the backend service on host port 3001 (or your custom port)
* Expose the client service on host port 3002 (or your custom port)

<Callout type="info">
  For detailed configuration examples with Nginx, Traefik, NPM, and other reverse proxies, see our [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) guide.
</Callout>

## Environment Variables [#environment-variables]

The setup script creates a minimal `.env` file with only the essential variables:

```bash
DOMAIN_NAME=your.domain.com
BASE_URL=https://your.domain.com
BETTER_AUTH_SECRET=generated_secret
DISABLE_SIGNUP=false
```

Optional variables that can be added:

```bash
# Mapbox token for 3D map visualizations
MAPBOX_TOKEN=your_mapbox_token

# Database configuration (uses defaults if not specified)
CLICKHOUSE_PASSWORD=frog
POSTGRES_USER=frog
POSTGRES_PASSWORD=frog
POSTGRES_DB=analytics
CLICKHOUSE_DB=analytics

# Custom image tags
IMAGE_TAG=latest

# Port mapping (only needed for custom ports or --no-webserver)
HOST_BACKEND_PORT="3001:3001"
HOST_CLIENT_PORT="3002:3002"
```


# Manual Docker Compose setup (/fr/docs/self-hosting-guides/self-hosting-manual)





This guide is for users who want to manually set up Rybbit using Docker Compose without the setup script. This is useful if you already have a reverse proxy setup (like Nginx, Traefik, or Coolify), or if you want more control over the configuration.

## Prerequisites [#prerequisites]

* Docker and Docker Compose installed
* A domain name pointed to your server
* Basic knowledge of Docker and environment variables

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Clone the Repository [#clone-the-repository]

    ```bash
    git clone https://github.com/rybbit-io/rybbit.git
    cd rybbit
    ```
  </Step>

  <Step>
    ### Create Environment File [#create-environment-file]

    Create a `.env` file in the root directory with the following content:

    ```bash
    # Required: Your domain and base URL
    DOMAIN_NAME=your.domain.com
    BASE_URL=https://your.domain.com

    # Required: Authentication secret (generate a random 32+ character string)
    BETTER_AUTH_SECRET=your-very-long-random-secret-string-here

    # Optional: Disable new user signups after creating admin account
    DISABLE_SIGNUP=false

    # Optional but recommended: Mapbox token for globe visualizations
    MAPBOX_TOKEN=your_mapbox_token

    # Optional: Custom ports (only needed if you want different ports)
    # HOST_BACKEND_PORT="3001:3001"
    # HOST_CLIENT_PORT="3002:3002"

    # Optional: Database credentials (defaults work fine)
    # CLICKHOUSE_PASSWORD=frog
    # POSTGRES_USER=frog
    # POSTGRES_PASSWORD=frog
    # POSTGRES_DB=analytics
    # CLICKHOUSE_DB=analytics
    ```

    <Callout type="info">
      To generate a secure `BETTER_AUTH_SECRET`, you can use:

      ```bash
      openssl rand -hex 32
      ```
    </Callout>
  </Step>

  <Step>
    ### Choose Your Setup Method [#choose-your-setup-method]

    <Tabs items="['Built-in Caddy (Automatic SSL)', 'Without Caddy']">
      <Tab value="Built-in Caddy (Automatic SSL)">
        If you don't have a reverse proxy and want automatic SSL certificates, use the default docker-compose.yml:

        ```bash
        docker compose up -d
        ```

        This will:

        * Start all services including Caddy
        * Automatically obtain SSL certificates
        * Make your app available at `https://your.domain.com`
      </Tab>

      <Tab value="Without Caddy">
        If you have your own reverse proxy (Nginx, Traefik, Coolify, etc.), you need to exclude Caddy and expose the ports:

        1. **Option B1: Modify the .env file**

           ```bash
           # Add these lines to expose ports
           HOST_BACKEND_PORT="3001:3001"
           HOST_CLIENT_PORT="3002:3002"
           ```

           Then start without Caddy:

           ```bash
           docker compose up -d backend client clickhouse postgres
           ```

        2. **Option B2: Use docker-compose.override.yml**
           Create a `docker-compose.override.yml` file:

           ```yaml
           services:
             backend:
               ports:
                 - "3001:3001"
             client:
               ports:
                 - "3002:3002"
           ```

           Then start without Caddy:

           ```bash
           docker compose up -d backend client clickhouse postgres
           ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure Your Reverse Proxy [#configure-your-reverse-proxy]

    If you're using your own reverse proxy, configure it to:

    * Proxy requests to `/api/*` to `http://localhost:3001`
    * Proxy all other requests to `http://localhost:3002`

    Example configurations:

    <Tabs items="['Nginx', 'Traefik']">
      <Tab value="Nginx">
        ```nginx
        server {
            listen 80;
            server_name your.domain.com;
            return 301 https://$host$request_uri;
        }

        server {
            listen 443 ssl;
            server_name your.domain.com;

            # Your SSL configuration here

            location /api/ {
                proxy_pass http://localhost:3001;
                proxy_set_header Host $host;
                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;
            }

            location / {
                proxy_pass http://localhost:3002;
                proxy_set_header Host $host;
                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;
            }
        }
        ```
      </Tab>

      <Tab value="Traefik">
        ```yml
        services:
          backend:
            labels:
              - "traefik.enable=true"
              - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && PathPrefix(`/api`)"
              - "traefik.http.routers.rybbit-api.tls.certresolver=letsencrypt"
              - "traefik.http.services.rybbit-api.loadbalancer.server.port=3001"
          
          client:
            labels:
              - "traefik.enable=true"
              - "traefik.http.routers.rybbit-client.rule=Host(`your.domain.com`)"
              - "traefik.http.routers.rybbit-client.tls.certresolver=letsencrypt"
              - "traefik.http.services.rybbit-client.loadbalancer.server.port=3002"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Start the Services [#start-the-services]

    ```bash
    # Start all services
    docker compose up -d

    # Or start specific services (without Caddy)
    docker compose up -d backend client clickhouse postgres
    ```
  </Step>

  <Step>
    ### Verify Setup [#verify-setup]

    Check that all services are running:

    ```bash
    docker compose ps
    ```

    Monitor logs:

    ```bash
    docker compose logs -f
    ```
  </Step>

  <Step>
    ### Create Admin Account [#create-admin-account]

    Navigate to `https://your.domain.com/signup` and create your admin account.
  </Step>
</Steps>

## Service Architecture [#service-architecture]

Rybbit consists of these services:

* **client**: Next.js frontend (port 3002)
* **backend**: Node.js API server (port 3001)
* **postgres**: User data and configuration
* **clickhouse**: Analytics data storage
* **redis**: Session tracking and background job queues
* **caddy**: Reverse proxy with automatic SSL (optional)

## Common Configurations [#common-configurations]

### Using Custom Ports [#using-custom-ports]

If you need different host ports (e.g., if 3001/3002 are already in use):

```bash
HOST_BACKEND_PORT="8080:3001"
HOST_CLIENT_PORT="8081:3002"
```

### Using with Coolify [#using-with-coolify]

Since Coolify uses Traefik instead of Caddy as proxy, some modifications have to be made in a `docker-compose.yaml` file to avoid conflicts. Specifically, you need to:

* remove Caddy service and volumes
* add network labels to all services
* remove `build` and `ports` properties from backend and client services

Here's a modified version of docker-compose that works on Coolify:

```yaml
services:
  clickhouse:
    container_name: clickhouse
    image: clickhouse/clickhouse-server:26.3.17.4
    volumes:
      - clickhouse-data:/var/lib/clickhouse
    configs:
      - source: clickhouse_network
        target: /etc/clickhouse-server/config.d/network.xml
      - source: clickhouse_logging
        target: /etc/clickhouse-server/config.d/logging_rules.xml
      # Profile (user-level) settings are only read from users.d, not config.d
      - source: clickhouse_user_settings
        target: /etc/clickhouse-server/users.d/user_settings.xml
    environment:
      - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
      - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
      - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://localhost:8123/ping",
        ]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    labels:
      - traefik.enable=false

  postgres:
    image: postgres:17.4
    container_name: postgres
    environment:
      - POSTGRES_USER=${POSTGRES_USER:-frog}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
      - POSTGRES_DB=${POSTGRES_DB:-analytics}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    labels:
      - traefik.enable=false

  redis:
    image: redis:8.6.4-alpine
    container_name: redis
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-changeme}", "--no-auth-warning", "ping"]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 5s
    restart: unless-stopped
    command:
      - redis-server
      - --requirepass
      - ${REDIS_PASSWORD:-changeme}
      - --appendonly
      - "yes"
      - --appendfsync
      - everysec
      - --maxmemory-policy
      - noeviction
    labels:
      - traefik.enable=false

  backend:
    image: ghcr.io/rybbit-io/rybbit-backend:${IMAGE_TAG:-latest}
    container_name: backend
    environment:
      - NODE_ENV=production
      - CLICKHOUSE_HOST=http://clickhouse:8123
      - CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}
      - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_DB=${POSTGRES_DB:-analytics}
      - POSTGRES_USER=${POSTGRES_USER:-frog}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-frog}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_PASSWORD=${REDIS_PASSWORD:-changeme}
      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
      - BASE_URL=${BASE_URL}
      - DOMAIN_NAME=${DOMAIN_NAME}
      - DISABLE_SIGNUP=${DISABLE_SIGNUP}
      - DISABLE_TELEMETRY=${DISABLE_TELEMETRY}
      - MAPBOX_TOKEN=${MAPBOX_TOKEN}
    depends_on:
      clickhouse:
        condition: service_healthy
      postgres:
        condition: service_started
      redis:
        condition: service_healthy
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://127.0.0.1:3001/api/health",
        ]
      interval: 3s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    labels:
      - traefik.enable=true
      - traefik.docker.network=coolify
      - traefik.http.routers.rybbit-backend.entrypoints=https
      - traefik.http.routers.rybbit-backend.tls=true
      - traefik.http.routers.rybbit-backend.rule=Host(`${DOMAIN_NAME}`) && (Path(`/api`) || PathPrefix(`/api/`))
      - traefik.http.services.rybbit-backend.loadbalancer.server.port=3001
      - traefik.http.routers.rybbit-backend.priority=100
      - traefik.http.middlewares.rybbit-forward-headers.headers.customrequestheaders.X-Forwarded-Proto=https
      - traefik.http.middlewares.rybbit-forward-headers.headers.customrequestheaders.X-Forwarded-Host=${DOMAIN_NAME}
      - traefik.http.routers.rybbit-backend.middlewares=rybbit-forward-headers

  client:
    image: ghcr.io/rybbit-io/rybbit-client:${IMAGE_TAG:-latest}
    container_name: client
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_BACKEND_URL=${BASE_URL}
      - NEXT_PUBLIC_DISABLE_SIGNUP=${DISABLE_SIGNUP}
      - DOMAIN_NAME=${DOMAIN_NAME}
    depends_on:
      - backend
    restart: unless-stopped
    labels:
      - traefik.enable=true
      - traefik.docker.network=coolify
      - traefik.http.routers.rybbit-client.entrypoints=https
      - traefik.http.routers.rybbit-client.tls=true
      - traefik.http.routers.rybbit-client.rule=Host(`${DOMAIN_NAME}`)
      - traefik.http.services.rybbit-client.loadbalancer.server.port=3002
      - traefik.http.routers.rybbit-client.priority=10

volumes:
  clickhouse-data:
  postgres-data:
  redis-data:

configs:
  clickhouse_network:
    content: |
      <clickhouse>
          <listen_host>0.0.0.0</listen_host>
      </clickhouse>

  clickhouse_logging:
    content: |
      <clickhouse>
        <logger>
            <level>warning</level>
            <console>true</console>
        </logger>
        <query_thread_log remove="remove"/>
        <query_log remove="remove"/>
        <text_log remove="remove"/>
        <trace_log remove="remove"/>
        <metric_log remove="remove"/>
        <asynchronous_metric_log remove="remove"/>
        <session_log remove="remove"/>
        <part_log remove="remove"/>
        <latency_log remove="remove"/>
        <processors_profile_log remove="remove"/>
      </clickhouse>

  clickhouse_user_settings:
    content: |
      <clickhouse>
        <profiles>
          <default>
            <enable_json_type>1</enable_json_type>
            <!-- 26.3+ enables async_insert by default; the backend already
                 batches app-side, so keep inserts synchronous -->
            <async_insert>0</async_insert>
            <log_queries>0</log_queries>
            <log_query_threads>0</log_query_threads>
            <log_processors_profiles>0</log_processors_profiles>
          </default>
        </profiles>
      </clickhouse>
```

To deploy Rybbit on Coolify, you need to:

1. Create a new project and resource using `docker-compose.yaml` file provided above
2. Make sure "Escape special characters in labels" option is unchecked when adding docker-compose file so that env variables in labels are read properly
3. Set the environment variables in Coolify's interface
4. Add a domain for `client` service in Coolify's interface
5. Deploy all services

Note: you don't need to add a domain for `backend` service in Coolify since client and backend services share the same domain.

### Using with Nginx Proxy Manager [#using-with-nginx-proxy-manager]

1. Set up port exposure in your .env:
   ```bash
   HOST_BACKEND_PORT="3001:3001"
   HOST_CLIENT_PORT="3002:3002"
   ```

2. Create a proxy host pointing to your server IP:3002

3. Add a custom location `/api/*` pointing to your server IP:3001

### Database Persistence [#database-persistence]

Data is automatically persisted in Docker volumes:

* `rybbit_clickhouse-data`: Analytics data
* `rybbit_postgres-data`: User accounts and site configurations

## Advanced Configurations [#advanced-configurations]

For specific reverse proxy setups, see our detailed guides:

* **[Custom Nginx Setup](/docs/self-hosting-guides/custom-nginx)** - Complete Nginx configuration with SSL
* **[Nginx Proxy Manager](/docs/self-hosting-guides/nginx-proxy-manager)** - NPM setup without port exposure

These guides provide step-by-step instructions for integrating Rybbit with your existing infrastructure.

## Troubleshooting [#troubleshooting]

### Services won't start [#services-wont-start]

```bash
# Check logs
docker compose logs

# Check service status
docker compose ps
```

### Port conflicts [#port-conflicts]

If you get port binding errors, either:

1. Change the host ports in your .env file
2. Stop the conflicting service
3. Use docker-compose.override.yml to customize ports

### Database connection issues [#database-connection-issues]

Ensure the database services are healthy:

```bash
docker compose ps
```

Both postgres and clickhouse should show "healthy" status.

<Callout type="info">
  For more advanced configurations and setup script options, see our [Advanced Self-Hosting Guide](/docs/self-hosting-guides/self-hosting-advanced).
</Callout>


# Create Annotation (/fr/docs/api/annotations/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/annotations
    ```

    Creates an annotation. Any member with access to the site can create site annotations; organization-wide annotations (`scope: "organization"`) require an admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  title: { description: 'Short title (max 120 characters)', type: 'string', required: true },
  date: { description: 'ISO 8601 timestamp with Z or offset, or YYYY-MM-DD (read as midnight UTC)', type: 'string', required: true },
  endDate: { description: 'End of a range; must be after date', type: 'string', required: false },
  description: { description: 'Longer note (max 2000 characters)', type: 'string', required: false },
  color: { description: 'Marker color', type: 'string', typeDescription: '&#x22;amber&#x22; | &#x22;rose&#x22; | &#x22;sky&#x22; | &#x22;violet&#x22; | &#x22;lime&#x22;', required: false },
  icon: { description: 'A single emoji (or character) shown in the marker', type: 'string', required: false },
  isPublic: { description: 'Show on public dashboards and private links', type: 'boolean', default: 'false', required: false },
  scope: { description: 'Attach to this site or to every site in the organization', type: 'string', typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;', default: '&#x22;site&#x22;', required: false },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: { description: 'Always true', type: 'boolean' },
  annotationId: { description: 'ID of the new annotation', type: 'number' },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl -X POST "https://app.rybbit.io/api/sites/123/annotations" \
          -H "Authorization: Bearer YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "title": "Deployed v2.3.0",
            "date": "2026-08-24T14:10:00Z",
            "color": "sky",
            "scope": "organization"
          }'
        ```
      </Tab>

      <Tab value="Response">
        ```json
        { "success": true, "annotationId": 43 }
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Delete Annotation (/fr/docs/api/annotations/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/annotations/:annotationId
    ```

    Deletes an annotation. Admins and owners can delete any annotation on their sites; members can delete only the annotations they created.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: { description: 'Site ID or site identifier', type: 'string | number', required: true },
  annotationId: { description: 'Annotation ID', type: 'number', required: true },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE "https://app.rybbit.io/api/sites/123/annotations/43" \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab value="Response">
        ```json
        { "success": true }
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Get Annotations (/fr/docs/api/annotations/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/annotations
    ```

    Returns the annotations pinned to the site's traffic chart, ordered by date. Organization-wide annotations (those with a `null` `siteId`) are included for every site in the organization.

    Anonymous viewers of a public dashboard or a private link only receive annotations with `isPublic: true`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  start_date: {
    description: 'Only annotations that end on or after the start of this day (YYYY-MM-DD). May be sent without end_date.',
    type: 'string',
    required: false,
  },
  end_date: {
    description: 'Only annotations that start before the end of this day (YYYY-MM-DD). May be sent without start_date; must not precede start_date.',
    type: 'string',
    required: false,
  },
  time_zone: {
    description: 'IANA timezone the day bounds are read in',
    type: 'string',
    default: 'UTC',
    required: false,
  },
}"
    />

    ### Response [#response]

    An array of annotation objects.

    <TypeTable
      type="{
  annotationId: { description: 'Unique annotation ID', type: 'number' },
  siteId: { description: 'Site the annotation belongs to, or null for organization-wide annotations', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator user ID', type: 'string | null' },
  userName: { description: 'Creator display name', type: 'string | null' },
  title: { description: 'Short title shown on the chart', type: 'string' },
  description: { description: 'Longer note', type: 'string | null' },
  date: { description: 'ISO 8601 timestamp the annotation is pinned to', type: 'string' },
  endDate: { description: 'ISO 8601 end timestamp for range annotations', type: 'string | null' },
  color: { description: 'Marker color', type: 'string | null', typeDescription: '&#x22;amber&#x22; | &#x22;rose&#x22; | &#x22;sky&#x22; | &#x22;violet&#x22; | &#x22;lime&#x22; | null' },
  icon: { description: 'Single emoji shown in the marker', type: 'string | null' },
  isPublic: { description: 'Whether public dashboards and private links show it', type: 'boolean' },
  createdAt: { description: 'Creation timestamp', type: 'string' },
  updatedAt: { description: 'Last update timestamp', type: 'string' },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl "https://app.rybbit.io/api/sites/123/annotations?start_date=2026-08-01&end_date=2026-08-31" \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab value="Response">
        ```json
        [
          {
            "annotationId": 42,
            "siteId": 123,
            "organizationId": "org_abc",
            "userId": "user_xyz",
            "userName": "Bill",
            "title": "Product Hunt launch",
            "description": "Finished #2 Product of the Day.",
            "date": "2026-08-18T07:00:00.000Z",
            "endDate": null,
            "color": "amber",
            "icon": "🚀",
            "isPublic": true,
            "createdAt": "2026-08-18 07:05:12.1",
            "updatedAt": "2026-08-18 07:05:12.1"
          }
        ]
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Update Annotation (/fr/docs/api/annotations/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:site/annotations/:annotationId
    ```

    Partial update: only the fields you send change. Admins and owners can edit any annotation on their sites; members can edit only the annotations they created. Changing `scope` requires an admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: { description: 'Site ID or site identifier', type: 'string | number', required: true },
  annotationId: { description: 'Annotation ID', type: 'number', required: true },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  title: { description: 'Short title (max 120 characters)', type: 'string', required: false },
  date: { description: 'ISO 8601 timestamp with Z or offset, or YYYY-MM-DD', type: 'string', required: false },
  endDate: { description: 'End of a range, or null to turn a range back into a point', type: 'string | null', required: false },
  description: { description: 'Longer note, or null to clear', type: 'string | null', required: false },
  color: { description: 'Marker color, or null for the neutral default', type: 'string | null', required: false },
  icon: { description: 'A single emoji (or character), or null to clear', type: 'string | null', required: false },
  isPublic: { description: 'Show on public dashboards and private links', type: 'boolean', required: false },
  scope: { description: 'Move between site and organization-wide', type: 'string', typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;', required: false },
}"
    />
  </div>

  <div>
    ### Example [#example]

    <Tabs items="['cURL', 'Response']">
      <Tab value="cURL">
        ```bash
        curl -X PUT "https://app.rybbit.io/api/sites/123/annotations/43" \
          -H "Authorization: Bearer YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{ "title": "Deployed v2.3.0 (rolled back)", "color": "rose" }'
        ```
      </Tab>

      <Tab value="Response">
        ```json
        { "success": true }
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Create Organization API Key (/fr/docs/api/api-keys/create-org)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/api-keys
    ```

    Creates an API key **owned by the organization itself**, rather than by your user account. The key authenticates as the organization (org-admin authority over its sites), so it survives member departures, and its plan gating, [rate limits](/docs/api/getting-started#rate-limits-cloud-only), and key-count limit all follow the owning organization's subscription. Organization keys are issued with the `rb_org_` prefix.

    <Callout type="warn">
      You must be an 

      **owner or admin**

       of the target organization. This endpoint accepts your dashboard 

      **session**

       or an 

      **unrestricted (full-access) user API key**

       — scoped keys and organization keys are rejected, so an organization key cannot mint other keys.
    </Callout>

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'The ID of the organization that will own the key',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'A label for the key',
    type: 'string',
    required: true,
  },
  expiresIn: {
    description: 'Seconds until the key expires. Omit for a key that never expires.',
    type: 'number',
    required: false,
  },
  permissions: {
    description: 'Scope the key to specific `resource: action[]` pairs (e.g. `{ &#x22;analytics&#x22;: [&#x22;read&#x22;], &#x22;goals&#x22;: [&#x22;read&#x22;, &#x22;write&#x22;] }`). Omit entirely for a full-access key.',
    type: 'object',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created API key object. The full `key` value carries the `rb_org_` prefix.

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  key: {
    description: 'The secret key value (prefixed with `rb_org_`)',
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string',
  },
  start: {
    description: 'A non-secret prefix of the key for display',
    type: 'string',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string',
  },
  referenceId: {
    description: 'The ID of the organization that owns the key',
    type: 'string',
  },
  userId: {
    description: 'The ID of the admin/owner who created the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if the key never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
}"
    />

    **Note:** Additional fields may be present in the response object.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_123/api-keys" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"name": "CI pipeline", "expiresIn": 2592000}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations/org_123/api-keys',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'CI pipeline',
              expiresIn: 2592000
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/organizations/org_123/api-keys',
            json={
                'name': 'CI pipeline',
                'expiresIn': 2592000
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/org_123/api-keys");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'name' => 'CI pipeline',
            'expiresIn' => 2592000
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/organizations/org_123/api-keys")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          name: 'CI pipeline',
          expiresIn: 2592000
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "name": "CI pipeline",
          "expiresIn": 2592000
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/org_123/api-keys", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/organizations/org_123/api-keys")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "name": "CI pipeline",
                "expiresIn": 2592000
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/org_123/api-keys"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/organizations/org_123/api-keys", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    <Callout type="warn">
      The full 

      `key`

       value is returned 

      **only once**

      , at creation. Store it securely — it cannot be retrieved again.
    </Callout>

    ```json title="Response"
    {
      "id": "key_8f3a1b2c4d5e6f7g",
      "key": "rb_org_xxxxxxxxxxxxxxxxxxxx",
      "name": "CI pipeline",
      "start": "rb_org_xxxx",
      "prefix": "rb_org_",
      "referenceId": "org_123",
      "userId": "user_2a9b8c7d6e5f4g3h",
      "enabled": true,
      "expiresAt": "2026-07-25T12:00:00.000Z",
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-25T12:00:00.000Z",
      "rateLimitEnabled": false,
      "rateLimitMax": 10,
      "rateLimitTimeWindow": 86400000
    }
    ```

    <Callout>
      On Rybbit Cloud, organization API keys require the organization to be on a Standard or Pro plan; free/basic plans receive HTTP 403. Each organization also has a plan-based key-count limit — creating a key past the limit returns HTTP 403.
    </Callout>
  </div>
</div>


# Create API Key (/fr/docs/api/api-keys/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/user/api-keys
    ```

    Creates a new API key scoped to your user account (and its organizations). To create a key owned by an organization instead, see [Create Organization API Key](/docs/api/api-keys/create-org).

    <Callout type="warn">
      This endpoint accepts your logged-in dashboard 

      **session**

       or an 

      **unrestricted (full-access) user API key**

      . Scoped keys and organization keys are rejected — so a scoped key cannot mint new keys, but a session or full-access key can. Send your session cookie or 

      `Authorization: Bearer`

       header with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'A label for the key',
    type: 'string',
    required: true,
  },
  expiresIn: {
    description: 'Seconds until the key expires. Omit for a key that never expires.',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created API key object.

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  key: {
    description: 'The secret key value',
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string',
  },
  start: {
    description: 'A non-secret prefix of the key for display',
    type: 'string',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string',
  },
  userId: {
    description: 'The ID of the user that owns the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if the key never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number',
  },
}"
    />

    **Note:** Additional fields may be present in the response object.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/user/api-keys" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"name": "CI pipeline", "expiresIn": 2592000}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/user/api-keys',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'CI pipeline',
              expiresIn: 2592000
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/user/api-keys',
            json={
                'name': 'CI pipeline',
                'expiresIn': 2592000
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/user/api-keys");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'name' => 'CI pipeline',
            'expiresIn' => 2592000
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/user/api-keys")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          name: 'CI pipeline',
          expiresIn: 2592000
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "name": "CI pipeline",
          "expiresIn": 2592000
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/user/api-keys", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/user/api-keys")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "name": "CI pipeline",
                "expiresIn": 2592000
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/user/api-keys"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"name\": \"CI pipeline\", \"expiresIn\": 2592000}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/user/api-keys", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    <Callout type="warn">
      The full 

      `key`

       value is returned 

      **only once**

      , at creation. Store it securely — it cannot be retrieved again.
    </Callout>

    ```json title="Response"
    {
      "id": "key_8f3a1b2c4d5e6f7g",
      "key": "rybbit_sk_live_xxxxxxxxxxxxxxxxxxxx",
      "name": "CI pipeline",
      "start": "rybbit_sk_live_xxxx",
      "prefix": "rybbit_sk_live_",
      "userId": "user_2a9b8c7d6e5f4g3h",
      "enabled": true,
      "expiresAt": "2026-07-25T12:00:00.000Z",
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-25T12:00:00.000Z",
      "rateLimitEnabled": false,
      "rateLimitMax": 10,
      "rateLimitTimeWindow": 86400000
    }
    ```

    <Callout>
      On Rybbit Cloud, API keys require a Standard or Pro plan; free/basic plans receive HTTP 403. 

      [Rate limits](/docs/api/getting-started#rate-limits-cloud-only)

       are charged to 

      **you**

      , the owning user, and are shared by every personal key you hold across every organization you belong to — creating a key does not add budget, and a plan change applies to keys you already have. For a budget that belongs to the organization instead, create an 

      [organization key](/docs/api/api-keys/create-org)

      .
    </Callout>
  </div>
</div>


# Delete API Key (/fr/docs/api/api-keys/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/api-key/delete
    ```

    Revokes (deletes) an existing API key. The key is identified by its `keyId`.

    <Callout type="warn">
      This endpoint uses 

      **POST**

      , not HTTP DELETE. Revoking a key is immediate and permanent — any client still using it will start receiving 401 responses.
    </Callout>

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  keyId: {
    description: 'The id of the API key to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns a success flag.

    <TypeTable
      type="{
  success: {
    description: 'Indicates the API key was successfully deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/api-key/delete" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"keyId": "key_8f3a1b2c4d5e6f7g"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/api-key/delete',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              keyId: 'key_8f3a1b2c4d5e6f7g'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/api-key/delete',
            json={
                'keyId': 'key_8f3a1b2c4d5e6f7g'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/api-key/delete");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'keyId' => 'key_8f3a1b2c4d5e6f7g'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/api-key/delete")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          keyId: 'key_8f3a1b2c4d5e6f7g'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "keyId": "key_8f3a1b2c4d5e6f7g"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/api-key/delete", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/api-key/delete")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "keyId": "key_8f3a1b2c4d5e6f7g"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/api-key/delete"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/api-key/delete", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# List API Keys (/fr/docs/api/api-keys/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/auth/api-key/list
    ```

    Returns all API keys owned by the authenticated user, or by a specific organization.

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID. If provided, returns organization-owned keys instead of your user-owned keys.',
    type: 'string',
    required: false,
  },
  limit: {
    description: 'Maximum number of keys to return.',
    type: 'number',
    required: false,
  },
  offset: {
    description: 'Number of keys to skip.',
    type: 'number',
    required: false,
  },
  sortBy: {
    description: 'Field to sort by (e.g. createdAt, name, expiresAt).',
    type: 'string',
    required: false,
  },
  sortDirection: {
    description: 'Sort direction.',
    type: &#x22;'asc' | 'desc'&#x22;,
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  apiKeys: {
    description: 'Array of API key objects.',
    type: 'ApiKey[]',
  },
  total: {
    description: 'Total number of matching keys.',
    type: 'number',
  },
  limit: {
    description: 'The limit that was applied.',
    type: 'number | null',
  },
  offset: {
    description: 'The offset that was applied.',
    type: 'number | null',
  },
}"
    />

    #### ApiKey Object [#apikey-object]

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string | null',
  },
  start: {
    description: 'Non-secret leading characters of the key, for display',
    type: 'string | null',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string | null',
  },
  userId: {
    description: 'ID of the user that owns the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if it never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
  requestCount: {
    description: 'Requests made in the current rate-limit window',
    type: 'number',
  },
  remaining: {
    description: 'Remaining requests, or null if not limited by count',
    type: 'number | null',
  },
  lastRequest: {
    description: 'Timestamp of the most recent request',
    type: 'string | null',
  },
  metadata: {
    description: 'Extra metadata stored on the key',
    type: 'object | null',
  },
  permissions: {
    description: 'Permissions associated with the key',
    type: 'object | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/auth/api-key/list?limit=20" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/api-key/list?limit=20',
          {
            method: 'GET',
            credentials: 'include'
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/auth/api-key/list?limit=20',
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/api-key/list?limit=20");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/api-key/list?limit=20")
        req = Net::HTTP::Get.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/auth/api-key/list?limit=20", nil)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/auth/api-key/list?limit=20")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/api-key/list?limit=20"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var response = await client.GetAsync("https://app.rybbit.io/api/auth/api-key/list?limit=20");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    <Callout>
      The secret key value is only returned once, at creation. This endpoint returns the non-secret 

      `start`

      /

      `prefix`

       for display, never the full key.
    </Callout>

    ```json title="Response"
    {
      "apiKeys": [
        {
          "id": "key_8f3a1b2c4d5e6f7g",
          "name": "CI pipeline",
          "start": "rybbit_sk_live_xxxx",
          "prefix": "rybbit_sk_live_",
          "userId": "user_2a9b8c7d6e5f4g3h",
          "enabled": true,
          "expiresAt": "2026-07-25T12:00:00.000Z",
          "createdAt": "2026-06-25T12:00:00.000Z",
          "updatedAt": "2026-06-25T12:00:00.000Z",
          "rateLimitEnabled": false,
          "rateLimitMax": 10,
          "rateLimitTimeWindow": 86400000,
          "requestCount": 42,
          "remaining": null,
          "lastRequest": "2026-06-25T13:30:00.000Z",
          "metadata": null,
          "permissions": null
        }
      ],
      "total": 1,
      "limit": 20,
      "offset": 0
    }
    ```
  </div>
</div>


# Update API Key (/fr/docs/api/api-keys/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/api-key/update
    ```

    <Callout>
      This endpoint uses 

      **POST**

      , not PUT or PATCH.
    </Callout>

    Updates mutable fields on an existing API key. The key is identified by its `keyId`.

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  keyId: {
    description: 'The id of the API key to update',
    type: 'string',
    required: true,
  },
  name: {
    description: 'A new label for the key',
    type: 'string',
    required: false,
  },
  enabled: {
    description: 'Enable or disable the key',
    type: 'boolean',
    required: false,
  },
  expiresIn: {
    description: 'New expiry in seconds from now. Pass null to make the key never expire.',
    type: 'number | null',
    required: false,
  },
  rateLimitEnabled: {
    description: 'Legacy per-key rate limit toggle. Has no effect — [rate limits](/docs/api/getting-started#rate-limits-cloud-only) are enforced per credential owner and follow that owner\'s plan',
    type: 'boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the updated API key object (without the secret key value).

    <TypeTable
      type="{
  id: {
    description: &#x22;The key's identifier&#x22;,
    type: 'string',
  },
  name: {
    description: 'The label for the key',
    type: 'string | null',
  },
  start: {
    description: 'Non-secret leading characters of the key, for display',
    type: 'string | null',
  },
  prefix: {
    description: 'The key prefix',
    type: 'string | null',
  },
  userId: {
    description: 'ID of the user that owns the key',
    type: 'string',
  },
  enabled: {
    description: 'Whether the key is currently enabled',
    type: 'boolean',
  },
  expiresAt: {
    description: 'Expiration timestamp, or null if it never expires',
    type: 'string | null',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
  },
  rateLimitEnabled: {
    description: 'Unused legacy field. Per-key rate limiting is off; limits apply per credential owner (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only))',
    type: 'boolean',
  },
  rateLimitMax: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
  rateLimitTimeWindow: {
    description: 'Unused legacy field. It is ignored — see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only) for the limits that actually apply',
    type: 'number | null',
  },
}"
    />

    **Note:** Additional fields may be present in the response object.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/api-key/update" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"keyId": "key_8f3a1b2c4d5e6f7g", "name": "CI pipeline (rotated)", "enabled": true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/api-key/update',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              keyId: 'key_8f3a1b2c4d5e6f7g',
              name: 'CI pipeline (rotated)',
              enabled: true
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/api-key/update',
            json={
                'keyId': 'key_8f3a1b2c4d5e6f7g',
                'name': 'CI pipeline (rotated)',
                'enabled': True
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/api-key/update");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'keyId' => 'key_8f3a1b2c4d5e6f7g',
            'name' => 'CI pipeline (rotated)',
            'enabled' => true
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/api-key/update")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          keyId: 'key_8f3a1b2c4d5e6f7g',
          name: 'CI pipeline (rotated)',
          enabled: true
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "keyId": "key_8f3a1b2c4d5e6f7g",
          "name": "CI pipeline (rotated)",
          "enabled": true
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/api-key/update", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/api-key/update")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "keyId": "key_8f3a1b2c4d5e6f7g",
                "name": "CI pipeline (rotated)",
                "enabled": true
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\", \"name\": \"CI pipeline (rotated)\", \"enabled\": true}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/api-key/update"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"keyId\": \"key_8f3a1b2c4d5e6f7g\", \"name\": \"CI pipeline (rotated)\", \"enabled\": true}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/api-key/update", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "key_8f3a1b2c4d5e6f7g",
      "name": "CI pipeline (rotated)",
      "start": "rybbit_sk_live_xxxx",
      "prefix": "rybbit_sk_live_",
      "userId": "user_2a9b8c7d6e5f4g3h",
      "enabled": true,
      "expiresAt": "2026-07-25T12:00:00.000Z",
      "createdAt": "2026-06-25T12:00:00.000Z",
      "updatedAt": "2026-06-26T12:00:00.000Z",
      "rateLimitEnabled": false,
      "rateLimitMax": 10,
      "rateLimitTimeWindow": 86400000
    }
    ```
  </div>
</div>


# Get AI Summary (/fr/docs/api/bots/ai-summary)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/ai-summary
    ```

    Returns one row per AI operator: how much of your site it read, and how many visits it sent back.

    The two numbers come from different places. Reads are bot events whose user agent names the operator; visits back are sessions in your normal analytics that arrived from that company's product (the `AI` acquisition channel). Neither is very interesting alone — "OpenAI read 4,120 pages and sent 12 visits" is the sentence this endpoint exists to produce.

    Operators that only read, and operators that only referred, both appear; the missing side reads `0`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Filters apply to both halves, using the bot filter subset described in [Get Bots by Dimension](/docs/api/bots/by-dimension).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of operator rows, ordered by reads descending',
    type: 'AiSummaryRow[]',
  },
}"
    />

    #### AiSummaryRow Object [#aisummaryrow-object]

    <TypeTable
      type="{
  operator: {
    description: 'Who runs the bot, e.g. &#x22;OpenAI&#x22;',
    type: 'string',
  },
  crawls: {
    description: 'Total AI requests from this operator',
    type: 'number',
  },
  training_crawls: {
    description: 'Requests with purpose ai_training',
    type: 'number',
  },
  search_crawls: {
    description: 'Requests with purpose ai_search',
    type: 'number',
  },
  agent_requests: {
    description: 'Requests with purpose ai_agent',
    type: 'number',
  },
  referrals: {
    description: 'Sessions that arrived from this operator\'s product',
    type: 'number',
  },
  crawls_per_referral: {
    description: 'Reads per visit sent back. 0 when the operator sent nobody back — there is no rate to report.',
    type: 'number',
  },
}"
    />

    <Callout>
      Only bots that execute JavaScript reach Rybbit. Crawlers that fetch HTML and run nothing — which includes most training crawlers — are absent unless your server reports them. See [Bot detection](/docs/bot-detection#reporting-crawlers-that-never-run-javascript).
    </Callout>
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/ai-summary?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/ai-summary?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/ai-summary',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York',
            },
            headers={'Authorization': 'Bearer your_api_key_here'},
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "operator": "OpenAI",
          "crawls": 6120,
          "training_crawls": 4400,
          "search_crawls": 900,
          "agent_requests": 820,
          "referrals": 214,
          "crawls_per_referral": 28.6
        },
        {
          "operator": "Perplexity",
          "crawls": 1904,
          "training_crawls": 0,
          "search_crawls": 1300,
          "agent_requests": 604,
          "referrals": 341,
          "crawls_per_referral": 5.6
        }
      ]
    }
    ```
  </div>
</div>


# Get Bots by Dimension (/fr/docs/api/bots/by-dimension)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/by-dimension
    ```

    Returns bot requests broken down by a dimension.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Bot filtering supports a subset of filter parameters: `browser`, `browser_version`, `operating_system`, `operating_system_version`, `country`, `region`, `city`, `device_type`, `referrer`, `hostname`, `pathname`, `querystring`, `dimensions`, `user_id`, `lat`, and `lon`.

    <TypeTable
      type="{
  dimension: {
    description: 'The dimension to group by',
    type: 'string',
    typeDescription: '&#x22;browser&#x22; | &#x22;browser_version&#x22; | &#x22;operating_system&#x22; | &#x22;operating_system_version&#x22; | &#x22;country&#x22; | &#x22;region&#x22; | &#x22;city&#x22; | &#x22;device_type&#x22; | &#x22;referrer&#x22; | &#x22;hostname&#x22; | &#x22;pathname&#x22; | &#x22;dimensions&#x22; | &#x22;asn_org&#x22; | &#x22;asn_provider&#x22; | &#x22;bot_category&#x22; | &#x22;bot_name&#x22; | &#x22;bot_operator&#x22; | &#x22;bot_purpose&#x22; | &#x22;matched_ua_pattern&#x22;',
    required: true,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  purpose: {
    description: 'Restrict results to one bot purpose. &#x22;ai&#x22; covers all three AI purposes; &#x22;ai_crawler&#x22; covers training and answer-engine crawling but not agents.',
    type: 'string',
    typeDescription: '&#x22;ai&#x22; | &#x22;ai_crawler&#x22; | &#x22;ai_training&#x22; | &#x22;ai_search&#x22; | &#x22;ai_agent&#x22; | &#x22;search&#x22; | &#x22;social_preview&#x22; | &#x22;seo&#x22; | &#x22;monitoring&#x22; | &#x22;security&#x22; | &#x22;scripted&#x22; | &#x22;headless&#x22;',
    required: false,
  },
  layer: {
    description: 'Restrict results to a single detection layer',
    type: 'string',
    typeDescription: '&#x22;ua_pattern&#x22; | &#x22;header_heuristics&#x22; | &#x22;client_signals&#x22; | &#x22;bot_asn&#x22; | &#x22;rate_anomaly&#x22;',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Paginated response object',
    type: 'PaginatedResponse',
  },
}"
    />

    #### PaginatedResponse Object [#paginatedresponse-object]

    <TypeTable
      type="{
  data: {
    description: 'Array of dimension breakdown objects',
    type: 'BotDimension[]',
  },
  totalCount: {
    description: 'Total number of distinct dimension values',
    type: 'number',
  },
}"
    />

    #### BotDimension Object [#botdimension-object]

    <TypeTable
      type="{
  value: {
    description: 'The dimension value',
    type: 'string',
  },
  hostname: {
    description: 'Hostname (only populated when dimension is &#x22;pathname&#x22;, otherwise empty)',
    type: 'string',
  },
  count: {
    description: 'Number of bot requests for this value',
    type: 'number',
  },
  percentage: {
    description: 'Share of bot requests for this value',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/by-dimension',
            params={
                'dimension': 'browser',
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/by-dimension?dimension=browser&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "data": [
          { "value": "Chrome", "hostname": "", "count": 980, "percentage": 53.26 },
          { "value": "HeadlessChrome", "hostname": "", "count": 540, "percentage": 29.35 }
        ],
        "totalCount": 12
      }
    }
    ```
  </div>
</div>


# Get Bot Overview (/fr/docs/api/bots/overview)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/overview
    ```

    Returns aggregate bot-traffic metrics with a breakdown by detection layer.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Bot filtering supports a subset of filter parameters: `browser`, `browser_version`, `operating_system`, `operating_system_version`, `country`, `region`, `city`, `device_type`, `referrer`, `hostname`, `pathname`, `querystring`, `dimensions`, `user_id`, `lat`, and `lon`.

    <TypeTable
      type="{
  layer: {
    description: 'Restrict results to a single detection layer',
    type: 'string',
    typeDescription: '&#x22;ua_pattern&#x22; | &#x22;header_heuristics&#x22; | &#x22;client_signals&#x22; | &#x22;bot_asn&#x22; | &#x22;rate_anomaly&#x22;',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  bot_requests: {
    description: 'Total bot requests',
    type: 'number',
  },
  total_events: {
    description: 'Total requests (bots + humans)',
    type: 'number',
  },
  bot_percentage: {
    description: 'Bot requests as a percentage of all requests',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  ai_requests: {
    description: 'Requests from named AI systems: training crawlers, answer-engine indexers, and user-triggered agents',
    type: 'number',
  },
  ai_agent_requests: {
    description: 'Requests from user-triggered AI agents (a person asked an assistant to open the page)',
    type: 'number',
  },
  ai_crawler_requests: {
    description: 'Requests from AI training crawlers and answer-engine indexers',
    type: 'number',
  },
  ua_pattern: {
    description: 'Bot requests flagged by the user-agent pattern layer',
    type: 'number',
  },
  header_heuristics: {
    description: 'Bot requests flagged by the header-heuristics layer',
    type: 'number',
  },
  client_signals: {
    description: 'Bot requests flagged by the client-signals layer',
    type: 'number',
  },
  bot_asn: {
    description: 'Bot requests flagged by the known-bot-ASN layer',
    type: 'number',
  },
  rate_anomaly: {
    description: 'Bot requests flagged by the rate-anomaly layer',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/overview',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "bot_requests": 1840,
        "total_events": 48933,
        "bot_percentage": 3.76,
        "ai_requests": 940,
        "ai_agent_requests": 180,
        "ai_crawler_requests": 760,
        "ua_pattern": 1200,
        "header_heuristics": 410,
        "client_signals": 95,
        "bot_asn": 120,
        "rate_anomaly": 15
      }
    }
    ```
  </div>
</div>


# Get Bot Time Series (/fr/docs/api/bots/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/bots/time-series
    ```

    Returns bot request counts over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    Bot filtering supports a subset of filter parameters: `browser`, `browser_version`, `operating_system`, `operating_system_version`, `country`, `region`, `city`, `device_type`, `referrer`, `hostname`, `pathname`, `querystring`, `dimensions`, `user_id`, `lat`, and `lon`.

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket granularity',
    type: 'string',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
  },
  purpose: {
    description: 'Restrict results to one bot purpose. &#x22;ai&#x22; covers all three AI purposes; &#x22;ai_crawler&#x22; covers training and answer-engine crawling but not agents.',
    type: 'string',
    typeDescription: '&#x22;ai&#x22; | &#x22;ai_crawler&#x22; | &#x22;ai_training&#x22; | &#x22;ai_search&#x22; | &#x22;ai_agent&#x22; | &#x22;search&#x22; | &#x22;social_preview&#x22; | &#x22;seo&#x22; | &#x22;monitoring&#x22; | &#x22;security&#x22; | &#x22;scripted&#x22; | &#x22;headless&#x22;',
    required: false,
  },
  layer: {
    description: 'Restrict results to a single detection layer',
    type: 'string',
    typeDescription: '&#x22;ua_pattern&#x22; | &#x22;header_heuristics&#x22; | &#x22;client_signals&#x22; | &#x22;bot_asn&#x22; | &#x22;rate_anomaly&#x22;',
    required: false,
  },
}"
    />

    #### Bucket Selection Guide [#bucket-selection-guide]

    | Bucket         | Best For                             |
    | -------------- | ------------------------------------ |
    | `minute`       | Real-time monitoring (last hour)     |
    | `five_minutes` | Short-term analysis (last few hours) |
    | `hour`         | Daily analysis                       |
    | `day`          | Weekly/monthly analysis              |
    | `week`         | Monthly/quarterly analysis           |
    | `month`        | Yearly analysis                      |

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
  },
  bot_requests: {
    description: 'Number of bot requests in this bucket',
    type: 'number',
  },
  ai_agent_requests: {
    description: 'Requests in this bucket from user-triggered AI agents',
    type: 'number',
  },
  ai_crawler_requests: {
    description: 'Requests in this bucket from AI training crawlers and answer-engine indexers',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/bots/time-series',
            params={
                'bucket': 'hour',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        { "time": "2024-01-15 13:00:00", "bot_requests": 42 },
        { "time": "2024-01-15 14:00:00", "bot_requests": 58 }
      ]
    }
    ```
  </div>
</div>


# Get Error Events (/fr/docs/api/errors/events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/errors/events
    ```

    Returns individual error occurrences for a specific error message, with full context including stack traces.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  errorMessage: {
    description: 'The error message to filter by',
    type: 'string',
    required: true,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    required: false,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 20,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of error event objects',
    type: 'ErrorEvent[]',
  },
}"
    />

    #### ErrorEvent Object [#errorevent-object]

    <TypeTable
      type="{
  timestamp: {
    description: 'When the error occurred',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  session_id: {
    description: 'Session identifier',
    type: 'string',
  },
  user_id: {
    description: 'User identifier',
    type: 'string | null',
  },
  pathname: {
    description: 'Page where error occurred',
    type: 'string',
  },
  hostname: {
    description: 'Hostname',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  message: {
    description: 'Error message',
    type: 'string',
  },
  stack: {
    description: 'Stack trace',
    type: 'string | null',
  },
  fileName: {
    description: 'Source file name',
    type: 'string | null',
  },
  lineNumber: {
    description: 'Line number in source',
    type: 'number | null',
  },
  columnNumber: {
    description: 'Column number in source',
    type: 'number | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          `https://app.rybbit.io/api/sites/1/errors/events?errorMessage=${encodeURIComponent("Cannot read property 'map' of undefined")}&limit=10`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/errors/events',
            params={
                'errorMessage': "Cannot read property 'map' of undefined",
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/errors/events?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "timestamp": "2024-01-31T14:22:00.000Z",
          "session_id": "sess_abc123",
          "user_id": "user_xyz789",
          "pathname": "/dashboard",
          "hostname": "app.example.com",
          "browser": "Chrome",
          "browser_version": "120.0.0",
          "operating_system": "macOS",
          "device_type": "desktop",
          "country": "US",
          "message": "Cannot read property 'map' of undefined",
          "stack": "TypeError: Cannot read property 'map' of undefined\n    at Dashboard (dashboard.js:42:15)\n    at renderWithHooks (react-dom.js:1234:22)",
          "fileName": "dashboard.js",
          "lineNumber": 42,
          "columnNumber": 15
        }
      ]
    }
    ```
  </div>
</div>


# Get Error Names (/fr/docs/api/errors/names)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/errors/names
    ```

    Returns a list of unique error messages with occurrence counts and affected session counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed). Enables paginated response format.',
    type: 'number',
    required: false,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 10,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of error objects (or paginated wrapper)',
    type: 'Error[] | PaginatedResponse',
  },
}"
    />

    #### Error Object [#error-object]

    <TypeTable
      type="{
  value: {
    description: 'Error message',
    type: 'string',
  },
  errorName: {
    description: 'Error type (TypeError, ReferenceError, etc.)',
    type: 'string',
  },
  count: {
    description: 'Total occurrences',
    type: 'number',
  },
  sessionCount: {
    description: 'Unique sessions affected',
    type: 'number',
  },
  percentage: {
    description: 'Percentage of total error sessions',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/errors/names',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/errors/names?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "value": "Cannot read property 'map' of undefined",
          "errorName": "TypeError",
          "count": 156,
          "sessionCount": 89,
          "percentage": 34.5
        },
        {
          "value": "NetworkError when attempting to fetch resource",
          "errorName": "TypeError",
          "count": 98,
          "sessionCount": 72,
          "percentage": 27.9
        },
        {
          "value": "foo is not defined",
          "errorName": "ReferenceError",
          "count": 45,
          "sessionCount": 38,
          "percentage": 14.7
        }
      ]
    }
    ```
  </div>
</div>


# Get Error Time Series (/fr/docs/api/errors/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/errors/time-series
    ```

    Returns error occurrence counts over time for a specific error message. Useful for tracking error trends and identifying when issues started.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  errorMessage: {
    description: 'The error message to filter by',
    type: 'string',
    required: true,
  },
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request succeeded',
    type: 'boolean',
  },
  data: {
    description: 'Array of time-bucketed counts',
    type: 'ErrorBucket[]',
  },
}"
    />

    #### ErrorBucket Object [#errorbucket-object]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  error_count: {
    description: 'Number of errors in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          `https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=${encodeURIComponent("Cannot read property 'map' of undefined")}&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/errors/time-series',
            params={
                'errorMessage': "Cannot read property 'map' of undefined",
                'bucket': 'hour',
                'start_date': '2024-01-30',
                'end_date': '2024-01-31',
                'time_zone': 'UTC'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/errors/time-series?errorMessage=Cannot%20read%20property%20%27map%27%20of%20undefined&bucket=hour&start_date=2024-01-30&end_date=2024-01-31&time_zone=UTC");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": [
        {
          "time": "2024-01-30T00:00:00.000Z",
          "error_count": 5
        },
        {
          "time": "2024-01-30T01:00:00.000Z",
          "error_count": 3
        },
        {
          "time": "2024-01-30T02:00:00.000Z",
          "error_count": 8
        },
        {
          "time": "2024-01-30T03:00:00.000Z",
          "error_count": 2
        }
      ]
    }
    ```
  </div>
</div>


# Get Event Counts (/fr/docs/api/events/count)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/count
    ```

    Returns time-bucketed event counts grouped by event type.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'day',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
  },
  pageview_count: {
    description: 'Number of pageviews in this bucket',
    type: 'number',
  },
  custom_event_count: {
    description: 'Number of custom events in this bucket',
    type: 'number',
  },
  performance_count: {
    description: 'Number of performance events in this bucket',
    type: 'number',
  },
  outbound_count: {
    description: 'Number of outbound link events in this bucket',
    type: 'number',
  },
  error_count: {
    description: 'Number of error events in this bucket',
    type: 'number',
  },
  button_click_count: {
    description: 'Number of button click events in this bucket',
    type: 'number',
  },
  copy_count: {
    description: 'Number of copy events in this bucket',
    type: 'number',
  },
  form_submit_count: {
    description: 'Number of form submit events in this bucket',
    type: 'number',
  },
  input_change_count: {
    description: 'Number of input change events in this bucket',
    type: 'number',
  },
  event_count: {
    description: 'Total events across all types in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/events/count',
            params={
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/events/count?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-15 00:00:00",
          "pageview_count": 4820,
          "custom_event_count": 312,
          "performance_count": 1200,
          "outbound_count": 88,
          "error_count": 14,
          "button_click_count": 540,
          "copy_count": 9,
          "form_submit_count": 33,
          "input_change_count": 120,
          "event_count": 7136
        }
      ]
    }
    ```
  </div>
</div>


# Get Events (/fr/docs/api/events/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events
    ```

    Returns a paginated list of events (pageviews, custom events, and outbound clicks).

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page_size: {
    description: 'Number of results per page',
    type: 'number',
    default: 50,
  },
  since_timestamp: {
    description: 'Poll for new events after this timestamp (ISO 8601). Used for realtime polling. Returns up to 500 events.',
    type: 'string',
  },
  before_timestamp: {
    description: 'Fetch events before this timestamp (ISO 8601). Used for cursor-based pagination (scrolling back).',
    type: 'string',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of event objects',
    type: 'Event[]',
  },
  cursor: {
    description: 'Cursor metadata for pagination (only present when not using since_timestamp)',
    type: '{ hasMore: boolean, oldestTimestamp: string | null }',
  },
}"
    />

    #### Event Object [#event-object]

    <TypeTable
      type="{
  timestamp: {
    description: 'Event timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;copy&#x22; | &#x22;form_submit&#x22; | &#x22;input_change&#x22;',
  },
  event_name: {
    description: 'Custom event name',
    type: 'string',
  },
  properties: {
    description: 'Event properties as JSON string',
    type: 'string',
  },
  session_id: {
    description: 'Session identifier',
    type: 'string',
  },
  user_id: {
    description: 'User identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Identified user ID (if user has been identified)',
    type: 'string',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
  },
  querystring: {
    description: 'URL query string',
    type: 'string',
  },
  hostname: {
    description: 'Hostname',
    type: 'string',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  language: {
    description: 'Browser language',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  lat: {
    description: 'Latitude',
    type: 'number',
  },
  lon: {
    description: 'Longitude',
    type: 'number',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events',
            params={
                'page_size': 50,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events?page_size=50&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "timestamp": "2024-01-31T14:22:00.000Z",
          "type": "custom_event",
          "event_name": "signup",
          "properties": "{\"plan\":\"pro\",\"source\":\"homepage\"}",
          "session_id": "abc123def456",
          "user_id": "user_abc123",
          "identified_user_id": "",
          "pathname": "/signup",
          "querystring": "",
          "hostname": "example.com",
          "page_title": "Sign Up",
          "referrer": "https://google.com",
          "browser": "Chrome",
          "browser_version": "120.0",
          "operating_system": "macOS",
          "operating_system_version": "14.0",
          "language": "en-US",
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "lat": 37.7749,
          "lon": -122.4194,
          "screen_width": 1920,
          "screen_height": 1080,
          "device_type": "desktop"
        },
        {
          "timestamp": "2024-01-31T14:21:00.000Z",
          "type": "pageview",
          "event_name": "",
          "properties": "{}",
          "session_id": "abc123def456",
          "user_id": "user_abc123",
          "identified_user_id": "",
          "pathname": "/pricing",
          "querystring": "",
          "hostname": "example.com",
          "page_title": "Pricing",
          "referrer": "https://example.com/",
          "browser": "Chrome",
          "browser_version": "120.0",
          "operating_system": "macOS",
          "operating_system_version": "14.0",
          "language": "en-US",
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "lat": 37.7749,
          "lon": -122.4194,
          "screen_width": 1920,
          "screen_height": 1080,
          "device_type": "desktop"
        }
      ],
      "cursor": {
        "hasMore": true,
        "oldestTimestamp": "2024-01-31T14:21:00.000Z"
      }
    }
    ```
  </div>
</div>


# Get Event Names (/fr/docs/api/events/names)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/names
    ```

    Returns a list of unique custom event names with their occurrence counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of event name objects',
    type: 'EventName[]',
  },
}"
    />

    #### EventName Object [#eventname-object]

    <TypeTable
      type="{
  eventName: {
    description: 'Name of the custom event',
    type: 'string',
  },
  count: {
    description: 'Number of occurrences',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events/names',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events/names?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "eventName": "signup",
          "count": 1250
        },
        {
          "eventName": "purchase",
          "count": 320
        },
        {
          "eventName": "add_to_cart",
          "count": 890
        },
        {
          "eventName": "newsletter_subscribe",
          "count": 456
        }
      ]
    }
    ```
  </div>
</div>


# Get Outbound Links (/fr/docs/api/events/outbound)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/outbound
    ```

    Returns a list of outbound link clicks with their occurrence counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of outbound link objects',
    type: 'OutboundLink[]',
  },
}"
    />

    #### OutboundLink Object [#outboundlink-object]

    <TypeTable
      type="{
  url: {
    description: 'The outbound URL that was clicked',
    type: 'string',
  },
  count: {
    description: 'Number of clicks',
    type: 'number',
  },
  lastClicked: {
    description: 'Most recent click timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events/outbound',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events/outbound?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "url": "https://github.com/example/repo",
          "count": 245,
          "lastClicked": "2024-01-31T14:22:00.000Z"
        },
        {
          "url": "https://twitter.com/example",
          "count": 189,
          "lastClicked": "2024-01-31T12:15:00.000Z"
        },
        {
          "url": "https://docs.example.com",
          "count": 156,
          "lastClicked": "2024-01-31T10:30:00.000Z"
        }
      ]
    }
    ```
  </div>
</div>


# Get Event Properties (/fr/docs/api/events/properties)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/properties
    ```

    Returns property key-value pairs for a specific event name with their occurrence counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  event_name: {
    description: 'Event name to get properties for',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of property objects',
    type: 'EventProperty[]',
  },
}"
    />

    #### EventProperty Object [#eventproperty-object]

    <TypeTable
      type="{
  propertyKey: {
    description: 'Property key name',
    type: 'string',
  },
  propertyValue: {
    description: 'Property value',
    type: 'string',
  },
  count: {
    description: 'Number of occurrences',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/events/properties',
            params={
                'event_name': 'signup',
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/events/properties?event_name=signup&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "propertyKey": "plan",
          "propertyValue": "pro",
          "count": 520
        },
        {
          "propertyKey": "plan",
          "propertyValue": "starter",
          "count": 430
        },
        {
          "propertyKey": "plan",
          "propertyValue": "enterprise",
          "count": 300
        },
        {
          "propertyKey": "source",
          "propertyValue": "homepage",
          "count": 650
        },
        {
          "propertyKey": "source",
          "propertyValue": "pricing",
          "count": 600
        }
      ]
    }
    ```
  </div>
</div>


# Get Event Time Series (/fr/docs/api/events/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/events/time-series
    ```

    Returns time-bucketed counts for the top custom events.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
  },
  limit: {
    description: 'Number of top custom events (by total count) to include',
    type: 'number',
    typeDescription: 'Range: 1-10',
    default: 5,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
  },
  event_name: {
    description: 'Name of the custom event',
    type: 'string',
  },
  event_count: {
    description: 'Number of times the event occurred in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/events/time-series',
            params={
                'bucket': 'hour',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York',
                'limit': 5
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/events/time-series?bucket=hour&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York&limit=5");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        { "time": "2024-01-15 13:00:00", "event_name": "signup", "event_count": 42 },
        { "time": "2024-01-15 13:00:00", "event_name": "purchase", "event_count": 12 }
      ]
    }
    ```
  </div>
</div>


# Analyze Funnel (/fr/docs/api/funnels/analyze)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/funnels/analyze
    ```

    Analyzes a funnel and returns step-by-step conversion data. Sessions must complete steps in order (step 2 must occur after step 1, etc.).

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Request Body [#request-body]

    <TypeTable
      type="{
  steps: {
    description: 'Array of funnel steps (minimum 2)',
    type: 'FunnelStep[]',
    required: true,
  },
}"
    />

    #### FunnelStep Object [#funnelstep-object]

    <TypeTable
      type="{
  type: {
    description: 'Step type',
    type: 'string',
    typeDescription: '&#x22;page&#x22; | &#x22;event&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;form_submit&#x22; | &#x22;copy&#x22;',
    required: true,
  },
  value: {
    description: 'Page path pattern or event name',
    type: 'string',
    required: true,
  },
  name: {
    description: 'Display name for the step',
    type: 'string',
    required: false,
  },
  hostname: {
    description: 'Filter by specific hostname',
    type: 'string',
    required: false,
  },
  eventPropertyKey: {
    description: 'Event property key to match (for event steps)',
    type: 'string',
    required: false,
  },
  eventPropertyValue: {
    description: 'Event property value to match',
    type: 'string | number | boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of step results',
    type: 'FunnelStepResult[]',
  },
}"
    />

    #### FunnelStepResult Object [#funnelstepresult-object]

    <TypeTable
      type="{
  step_number: {
    description: 'Step number (1-indexed)',
    type: 'number',
  },
  step_name: {
    description: 'Step name',
    type: 'string',
  },
  sessions: {
    description: 'Number of sessions that reached this step',
    type: 'number',
  },
  visitors: {
    description: 'Deprecated alias of `sessions`, kept for backwards compatibility',
    type: 'number',
  },
  conversion_rate: {
    description: 'Percentage of step 1 sessions that reached this step',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  dropoff_rate: {
    description: 'Percentage who dropped off from the previous step',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "steps": [
              { "type": "page", "value": "/", "name": "Homepage" },
              { "type": "page", "value": "/pricing", "name": "Pricing" },
              { "type": "page", "value": "/signup", "name": "Signup" },
              { "type": "event", "value": "signup_complete", "name": "Complete" }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              steps: [
                { type: 'page', value: '/', name: 'Homepage' },
                { type: 'page', value: '/pricing', name: 'Pricing' },
                { type: 'page', value: '/signup', name: 'Signup' },
                { type: 'event', value: 'signup_complete', name: 'Complete' }
              ]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/funnels/analyze',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            json={
                'steps': [
                    { 'type': 'page', 'value': '/', 'name': 'Homepage' },
                    { 'type': 'page', 'value': '/pricing', 'name': 'Pricing' },
                    { 'type': 'page', 'value': '/signup', 'name': 'Signup' },
                    { 'type': 'event', 'value': 'signup_complete', 'name': 'Complete' }
                ]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'steps' => [
                ['type' => 'page', 'value' => '/', 'name' => 'Homepage'],
                ['type' => 'page', 'value' => '/pricing', 'name' => 'Pricing'],
                ['type' => 'page', 'value' => '/signup', 'name' => 'Signup'],
                ['type' => 'event', 'value' => 'signup_complete', 'name' => 'Complete']
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          steps: [
            { type: 'page', value: '/', name: 'Homepage' },
            { type: 'page', value: '/pricing', name: 'Pricing' },
            { type: 'page', value: '/signup', name: 'Signup' },
            { type: 'event', value: 'signup_complete', name: 'Complete' }
          ]
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "bytes"
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            body := map[string]interface{}{
                "steps": []map[string]string{
                    {"type": "page", "value": "/", "name": "Homepage"},
                    {"type": "page", "value": "/pricing", "name": "Pricing"},
                    {"type": "page", "value": "/signup", "name": "Signup"},
                    {"type": "event", "value": "signup_complete", "name": "Complete"},
                },
            }
            jsonBody, _ := json.Marshal(body)

            client := &http.Client{}
            req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31", bytes.NewBuffer(jsonBody))
            req.Header.Set("Authorization", "Bearer your_api_key_here")
            req.Header.Set("Content-Type", "application/json")

            resp, _ := client.Do(req)
            defer resp.Body.Close()

            respBody, _ := io.ReadAll(resp.Body)
            var data map[string]interface{}
            json.Unmarshal(respBody, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::{json, Value};

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let body = json!({
                "steps": [
                    {"type": "page", "value": "/", "name": "Homepage"},
                    {"type": "page", "value": "/pricing", "name": "Pricing"},
                    {"type": "page", "value": "/signup", "name": "Signup"},
                    {"type": "event", "value": "signup_complete", "name": "Complete"}
                ]
            });

            let client = reqwest::Client::new();
            let response = client
                .post("https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31")
                .header("Authorization", "Bearer your_api_key_here")
                .header("Content-Type", "application/json")
                .json(&body)
                .send()
                .await?;

            let data: Value = response.json().await?;
            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        String json = """
        {
          "steps": [
            {"type": "page", "value": "/", "name": "Homepage"},
            {"type": "page", "value": "/pricing", "name": "Pricing"},
            {"type": "page", "value": "/signup", "name": "Signup"},
            {"type": "event", "value": "signup_complete", "name": "Complete"}
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        String data = response.body();
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System.Net.Http;
        using System.Net.Http.Headers;
        using System.Text;
        using System.Text.Json;

        var body = new
        {
            steps = new[]
            {
                new { type = "page", value = "/", name = "Homepage" },
                new { type = "page", value = "/pricing", name = "Pricing" },
                new { type = "page", value = "/signup", name = "Signup" },
                new { type = "event", value = "signup_complete", name = "Complete" }
            }
        };

        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync(
            "https://app.rybbit.io/api/sites/1/funnels/analyze?start_date=2024-01-01&end_date=2024-01-31",
            content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "step_number": 1,
          "step_name": "Homepage",
          "sessions": 10000,
          "conversion_rate": 100,
          "dropoff_rate": 0
        },
        {
          "step_number": 2,
          "step_name": "Pricing",
          "sessions": 4500,
          "conversion_rate": 45,
          "dropoff_rate": 55
        },
        {
          "step_number": 3,
          "step_name": "Signup",
          "sessions": 1800,
          "conversion_rate": 18,
          "dropoff_rate": 60
        },
        {
          "step_number": 4,
          "step_name": "Complete",
          "sessions": 720,
          "conversion_rate": 7.2,
          "dropoff_rate": 60
        }
      ]
    }
    ```
  </div>
</div>


# Create Funnel (/fr/docs/api/funnels/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/funnels
    ```

    Creates or updates a saved funnel. If `reportId` is provided, updates the existing funnel.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Funnel name',
    type: 'string',
    required: true,
  },
  steps: {
    description: 'Array of funnel steps (minimum 2)',
    type: 'FunnelStep[]',
    required: true,
  },
  reportId: {
    description: 'Existing funnel ID to update (optional)',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the funnel was created/updated',
    type: 'boolean',
  },
  funnelId: {
    description: 'ID of the created/updated funnel',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Create New Funnel"
        curl -X POST "https://app.rybbit.io/api/sites/1/funnels" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Checkout Funnel",
            "steps": [
              { "type": "page", "value": "/products/*", "name": "Product Page" },
              { "type": "page", "value": "/cart", "name": "Cart" },
              { "type": "page", "value": "/checkout", "name": "Checkout" },
              { "type": "event", "value": "purchase", "name": "Purchase" }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Update Existing Funnel"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              reportId: 1,  // Update existing funnel
              name: 'Checkout Funnel (Updated)',
              steps: [
                { type: 'page', value: '/products/*', name: 'Product Page' },
                { type: 'page', value: '/cart', name: 'Cart' },
                { type: 'page', value: '/checkout', name: 'Checkout' },
                { type: 'page', value: '/checkout/success', name: 'Success' }
              ]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/funnels',
            json={
                'name': 'Onboarding Funnel',
                'steps': [
                    { 'type': 'page', 'value': '/signup', 'name': 'Signup' },
                    { 'type': 'event', 'value': 'account_created', 'name': 'Account Created' },
                    { 'type': 'page', 'value': '/onboarding/*', 'name': 'Onboarding' },
                    { 'type': 'event', 'value': 'onboarding_complete', 'name': 'Complete' }
                ]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Checkout Funnel',
            'steps' => [
                ['type' => 'page', 'value' => '/products/*', 'name' => 'Product Page'],
                ['type' => 'page', 'value' => '/cart', 'name' => 'Cart'],
                ['type' => 'page', 'value' => '/checkout', 'name' => 'Checkout'],
                ['type' => 'event', 'value' => 'purchase', 'name' => 'Purchase']
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Checkout Funnel',
          steps: [
            { type: 'page', value: '/products/*', name: 'Product Page' },
            { type: 'page', value: '/cart', name: 'Cart' },
            { type: 'page', value: '/checkout', name: 'Checkout' },
            { type: 'event', value: 'purchase', name: 'Purchase' }
          ]
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Checkout Funnel",
            "steps": []map[string]string{
                {"type": "page", "value": "/products/*", "name": "Product Page"},
                {"type": "page", "value": "/cart", "name": "Cart"},
                {"type": "page", "value": "/checkout", "name": "Checkout"},
                {"type": "event", "value": "purchase", "name": "Purchase"},
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Checkout Funnel",
            "steps": [
                {"type": "page", "value": "/products/*", "name": "Product Page"},
                {"type": "page", "value": "/cart", "name": "Cart"},
                {"type": "page", "value": "/checkout", "name": "Checkout"},
                {"type": "event", "value": "purchase", "name": "Purchase"}
            ]
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/1/funnels")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Checkout Funnel",
          "steps": [
            {"type": "page", "value": "/products/*", "name": "Product Page"},
            {"type": "page", "value": "/cart", "name": "Cart"},
            {"type": "page", "value": "/checkout", "name": "Checkout"},
            {"type": "event", "value": "purchase", "name": "Purchase"}
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Checkout Funnel",
            steps = new[]
            {
                new { type = "page", value = "/products/*", name = "Product Page" },
                new { type = "page", value = "/cart", name = "Cart" },
                new { type = "page", value = "/checkout", name = "Checkout" },
                new { type = "event", value = "purchase", name = "Purchase" }
            }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/funnels", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "funnelId": 2
    }
    ```
  </div>
</div>


# Delete Funnel (/fr/docs/api/funnels/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/funnels/:funnelId
    ```

    Deletes a saved funnel. This action cannot be undone.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  funnelId: {
    description: 'ID of the funnel to delete',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the funnel was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/1/funnels/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels/123',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/1/funnels/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels/123')
        request = Net::HTTP::Delete.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/1/funnels/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/1/funnels/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/1/funnels/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Funnels (/fr/docs/api/funnels/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/funnels
    ```

    Returns all saved funnels for a site.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of saved funnels',
    type: 'Funnel[]',
  },
}"
    />

    #### Funnel Object [#funnel-object]

    <TypeTable
      type="{
  id: {
    description: 'Unique funnel identifier',
    type: 'number',
  },
  name: {
    description: 'Funnel name',
    type: 'string',
  },
  steps: {
    description: 'Array of funnel steps',
    type: 'FunnelStep[]',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/funnels" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/funnels',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels')
        request = Net::HTTP::Get.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            client := &http.Client{}
            req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/funnels", nil)
            req.Header.Set("Authorization", "Bearer your_api_key_here")

            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)
            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();
            let response = client
                .get("https://app.rybbit.io/api/sites/1/funnels")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;
            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        String data = response.body();
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System.Net.Http;
        using System.Net.Http.Headers;

        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "your_api_key_here");

        var response = await client.GetAsync(
            "https://app.rybbit.io/api/sites/1/funnels");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "id": 1,
          "name": "Signup Funnel",
          "steps": [
            { "type": "page", "value": "/", "name": "Homepage" },
            { "type": "page", "value": "/pricing", "name": "Pricing" },
            { "type": "page", "value": "/signup", "name": "Signup" },
            { "type": "page", "value": "/signup/complete", "name": "Complete" }
          ],
          "createdAt": "2024-01-10T12:00:00.000Z",
          "updatedAt": "2024-01-15T09:30:00.000Z"
        }
      ]
    }
    ```
  </div>
</div>


# Get Funnel Step Sessions (/fr/docs/api/funnels/step-sessions)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/funnels/:stepNumber/sessions
    ```

    Returns sessions that either reached or dropped off at a specific funnel step. Useful for analyzing user behavior at each stage.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  stepNumber: {
    description: 'Step number (1-indexed)',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  mode: {
    description: 'Whether to get sessions that reached or dropped off at this step',
    type: 'string',
    typeDescription: '&#x22;reached&#x22; | &#x22;dropped&#x22;',
    required: true,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 25,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  steps: {
    description: 'Array of funnel steps (same as used in analyze)',
    type: 'FunnelStep[]',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session objects',
    type: 'Session[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Get sessions that dropped off at step 2"
        curl -X POST "https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "steps": [
              { "type": "page", "value": "/", "name": "Homepage" },
              { "type": "page", "value": "/pricing", "name": "Pricing" },
              { "type": "page", "value": "/signup", "name": "Signup" }
            ]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Get sessions that reached step 3"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/funnels/3/sessions?mode=reached&page=1',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              steps: [
                { type: 'page', value: '/', name: 'Homepage' },
                { type: 'page', value: '/pricing', name: 'Pricing' },
                { type: 'page', value: '/signup', name: 'Signup' }
              ]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/funnels/2/sessions',
            params={
                'mode': 'dropped',
                'page': 1
            },
            json={
                'steps': [
                    { 'type': 'page', 'value': '/', 'name': 'Homepage' },
                    { 'type': 'page', 'value': '/pricing', 'name': 'Pricing' },
                    { 'type': 'page', 'value': '/signup', 'name': 'Signup' }
                ]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'steps' => [
                ['type' => 'page', 'value' => '/', 'name' => 'Homepage'],
                ['type' => 'page', 'value' => '/pricing', 'name' => 'Pricing'],
                ['type' => 'page', 'value' => '/signup', 'name' => 'Signup']
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          steps: [
            { type: 'page', value: '/', name: 'Homepage' },
            { type: 'page', value: '/pricing', name: 'Pricing' },
            { type: 'page', value: '/signup', name: 'Signup' }
          ]
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "steps": []map[string]string{
                {"type": "page", "value": "/", "name": "Homepage"},
                {"type": "page", "value": "/pricing", "name": "Pricing"},
                {"type": "page", "value": "/signup", "name": "Signup"},
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "steps": [
                {"type": "page", "value": "/", "name": "Homepage"},
                {"type": "page", "value": "/pricing", "name": "Pricing"},
                {"type": "page", "value": "/signup", "name": "Signup"}
            ]
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "steps": [
            {"type": "page", "value": "/", "name": "Homepage"},
            {"type": "page", "value": "/pricing", "name": "Pricing"},
            {"type": "page", "value": "/signup", "name": "Signup"}
          ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            steps = new[]
            {
                new { type = "page", value = "/", name = "Homepage" },
                new { type = "page", value = "/pricing", name = "Pricing" },
                new { type = "page", value = "/signup", name = "Signup" }
            }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync(
            "https://app.rybbit.io/api/sites/1/funnels/2/sessions?mode=dropped&page=1",
            content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "sess_abc123",
          "user_id": "user_xyz789",
          "country": "US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "entry_page": "/",
          "exit_page": "/pricing",
          "pageviews": 3,
          "session_duration": 125,
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:02:05.000Z",
          "referrer": "https://google.com",
          "channel": "organic"
        }
      ]
    }
    ```
  </div>
</div>


# Create Goal (/fr/docs/api/goals/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/goals
    ```

    Creates a new goal for tracking conversions.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Goal name',
    type: 'string',
    required: false,
  },
  goalType: {
    description: 'Type of goal',
    type: 'string',
    typeDescription: '&#x22;path&#x22; | &#x22;event&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;form_submit&#x22; | &#x22;copy&#x22;',
    required: true,
  },
  config: {
    description: 'Goal configuration',
    type: 'GoalConfig',
    required: true,
  },
}"
    />

    #### GoalConfig for Path Goals [#goalconfig-for-path-goals]

    <TypeTable
      type="{
  pathPattern: {
    description: 'URL path pattern to match. Supports wildcards (*)',
    type: 'string',
    required: true,
    typeDescription: 'e.g., &#x22;/checkout/*&#x22;, &#x22;/signup/complete&#x22;',
  },
}"
    />

    #### GoalConfig for Event Goals [#goalconfig-for-event-goals]

    <TypeTable
      type="{
  eventName: {
    description: 'Event name to match',
    type: 'string',
    required: true,
  },
  eventPropertyKey: {
    description: 'Property key to match (optional)',
    type: 'string',
    required: false,
  },
  eventPropertyValue: {
    description: 'Property value to match (required if key is provided)',
    type: 'string | number | boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the goal was created',
    type: 'boolean',
  },
  goalId: {
    description: 'ID of the created goal',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Path Goal"
        curl -X POST "https://app.rybbit.io/api/sites/1/goals" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Checkout Complete",
            "goalType": "path",
            "config": {
              "pathPattern": "/checkout/success"
            }
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Event Goal"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Purchase Made',
              goalType: 'event',
              config: {
                eventName: 'purchase',
                eventPropertyKey: 'plan',
                eventPropertyValue: 'pro'
              }
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/goals',
            json={
                'name': 'Signup Complete',
                'goalType': 'path',
                'config': {
                    'pathPattern': '/signup/*'
                }
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Checkout Complete',
            'goalType' => 'path',
            'config' => [
                'pathPattern' => '/checkout/success'
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/goals')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Checkout Complete',
          goalType: 'path',
          config: { pathPattern: '/checkout/success' }
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Checkout Complete",
            "goalType": "path",
            "config": map[string]string{
                "pathPattern": "/checkout/success",
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/1/goals", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Checkout Complete",
            "goalType": "path",
            "config": {
                "pathPattern": "/checkout/success"
            }
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/1/goals")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Checkout Complete",
          "goalType": "path",
          "config": {
            "pathPattern": "/checkout/success"
          }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/goals"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Checkout Complete",
            goalType = "path",
            config = new { pathPattern = "/checkout/success" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/1/goals", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "goalId": 3
    }
    ```
  </div>
</div>


# Delete Goal (/fr/docs/api/goals/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/goals/:goalId
    ```

    Deletes a goal. This action cannot be undone.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  goalId: {
    description: 'ID of the goal to delete',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the goal was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/1/goals/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals/123',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/1/goals/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/goals/123')
        request = Net::HTTP::Delete.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/1/goals/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/1/goals/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/goals/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/1/goals/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Goals (/fr/docs/api/goals/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/goals
    ```

    Returns a paginated list of goals with their conversion metrics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  page_size: {
    description: 'Number of results per page (max 100)',
    type: 'number',
    default: 10,
  },
  sort: {
    description: 'Field to sort by',
    type: 'string',
    typeDescription: '&#x22;goalId&#x22; | &#x22;name&#x22; | &#x22;goalType&#x22; | &#x22;createdAt&#x22;',
    default: 'createdAt',
  },
  order: {
    description: 'Sort direction',
    type: 'string',
    typeDescription: '&#x22;asc&#x22; | &#x22;desc&#x22;',
    default: 'desc',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of goal objects with conversion data',
    type: 'Goal[]',
  },
  meta: {
    description: 'Pagination metadata',
    type: 'PaginationMeta',
  },
}"
    />

    #### Goal Object [#goal-object]

    <TypeTable
      type="{
  goalId: {
    description: 'Unique goal identifier',
    type: 'number',
  },
  name: {
    description: 'Goal name',
    type: 'string | null',
  },
  goalType: {
    description: 'Type of goal',
    type: 'string',
    typeDescription: '&#x22;path&#x22; | &#x22;event&#x22;',
  },
  config: {
    description: 'Goal configuration',
    type: 'GoalConfig',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  total_conversions: {
    description: 'Number of sessions that completed the goal',
    type: 'number',
  },
  total_sessions: {
    description: 'Total sessions in the time period',
    type: 'number',
  },
  conversion_rate: {
    description: 'Conversion rate (0-1)',
    type: 'number',
  },
}"
    />

    #### GoalConfig Object [#goalconfig-object]

    <TypeTable
      type="{
  pathPattern: {
    description: 'URL path pattern (for path goals). Supports wildcards (*)',
    type: 'string',
    required: false,
  },
  eventName: {
    description: 'Event name to match (for event goals)',
    type: 'string',
    required: false,
  },
  eventPropertyKey: {
    description: 'Event property key to match',
    type: 'string',
    required: false,
  },
  eventPropertyValue: {
    description: 'Event property value to match',
    type: 'string | number | boolean',
    required: false,
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/goals',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        <?php
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ?>
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'
        require 'uri'

        uri = URI('https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(req)
        end

        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            url := "https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31"

            req, _ := http.NewRequest("GET", url, nil)
            req.Header.Add("Authorization", "Bearer your_api_key_here")

            client := &http.Client{}
            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)

            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();

            let response = client
                .get("https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;

            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class Main {
            public static void main(String[] args) throws Exception {
                HttpClient client = HttpClient.newHttpClient();

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31"))
                    .header("Authorization", "Bearer your_api_key_here")
                    .GET()
                    .build();

                HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

                String data = response.body();
            }
        }
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System;
        using System.Net.Http;
        using System.Threading.Tasks;

        class Program
        {
            static async Task Main(string[] args)
            {
                using var client = new HttpClient();

                client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

                var response = await client.GetAsync(
                    "https://app.rybbit.io/api/sites/1/goals?start_date=2024-01-01&end_date=2024-01-31");

                var data = await response.Content.ReadAsStringAsync();
            }
        }
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "goalId": 1,
          "name": "Signup Completed",
          "goalType": "path",
          "config": {
            "pathPattern": "/signup/complete"
          },
          "createdAt": "2024-01-10T12:00:00.000Z",
          "total_conversions": 1250,
          "total_sessions": 15420,
          "conversion_rate": 0.081
        },
        {
          "goalId": 2,
          "name": "Purchase Made",
          "goalType": "event",
          "config": {
            "eventName": "purchase",
            "eventPropertyKey": "value",
            "eventPropertyValue": 100
          },
          "createdAt": "2024-01-15T09:30:00.000Z",
          "total_conversions": 320,
          "total_sessions": 15420,
          "conversion_rate": 0.021
        }
      ],
      "meta": {
        "total": 2,
        "page": 1,
        "pageSize": 10,
        "totalPages": 1
      }
    }
    ```
  </div>
</div>


# Get Goal Sessions (/fr/docs/api/goals/sessions)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/goals/:goalId/sessions
    ```

    Returns sessions that completed a specific goal. Useful for analyzing the behavior of converting users.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  goalId: {
    description: 'Goal ID',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 25,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session objects',
    type: 'Session[]',
  },
}"
    />

    #### Session Object [#session-object]

    <TypeTable
      type="{
  session_id: {
    description: 'Unique session identifier',
    type: 'string',
  },
  user_id: {
    description: 'User identifier',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  entry_page: {
    description: 'First page visited',
    type: 'string',
  },
  exit_page: {
    description: 'Last page visited',
    type: 'string',
  },
  pageviews: {
    description: 'Number of pageviews',
    type: 'number',
  },
  session_duration: {
    description: 'Session duration in seconds',
    type: 'number',
  },
  session_start: {
    description: 'Session start time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  session_end: {
    description: 'Session end time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/goals/1/sessions',
            params={
                'page': 1,
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        <?php
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ?>
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'
        require 'uri'

        uri = URI('https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(req)
        end

        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            url := "https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10"

            req, _ := http.NewRequest("GET", url, nil)
            req.Header.Add("Authorization", "Bearer your_api_key_here")

            client := &http.Client{}
            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)

            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();

            let response = client
                .get("https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;

            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class Main {
            public static void main(String[] args) throws Exception {
                HttpClient client = HttpClient.newHttpClient();

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10"))
                    .header("Authorization", "Bearer your_api_key_here")
                    .GET()
                    .build();

                HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

                String data = response.body();
            }
        }
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System;
        using System.Net.Http;
        using System.Threading.Tasks;

        class Program
        {
            static async Task Main(string[] args)
            {
                using var client = new HttpClient();

                client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

                var response = await client.GetAsync(
                    "https://app.rybbit.io/api/sites/1/goals/1/sessions?page=1&limit=10");

                var data = await response.Content.ReadAsStringAsync();
            }
        }
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "sess_abc123",
          "user_id": "user_xyz789",
          "country": "US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "entry_page": "/",
          "exit_page": "/signup/complete",
          "pageviews": 5,
          "session_duration": 245,
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:04:05.000Z",
          "referrer": "https://google.com",
          "channel": "organic"
        }
      ]
    }
    ```
  </div>
</div>


# Get Goal Time Series (/fr/docs/api/goals/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/goals/time-series
    ```

    Returns goal conversions and conversion rate over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters) plus the following:

    <TypeTable
      type="{
  goal_ids: {
    description: 'The goals to include',
    type: 'string',
    typeDescription: 'Comma-separated goal IDs (e.g. &#x22;1,2&#x22;) or a JSON array. If omitted, the response is empty.',
    required: true,
  },
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
  },
}"
    />

    #### Bucket Selection Guide [#bucket-selection-guide]

    | Bucket         | Best For                             |
    | -------------- | ------------------------------------ |
    | `minute`       | Real-time monitoring (last hour)     |
    | `five_minutes` | Short-term analysis (last few hours) |
    | `hour`         | Daily analysis                       |
    | `day`          | Weekly/monthly analysis              |
    | `week`         | Monthly/quarterly analysis           |
    | `month`        | Yearly analysis                      |

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  goal_id: {
    description: 'ID of the goal',
    type: 'number',
  },
  conversions: {
    description: 'Number of distinct converting sessions in this bucket',
    type: 'number',
  },
  total_sessions: {
    description: 'Total number of sessions in this bucket',
    type: 'number',
  },
  conversion_rate: {
    description: 'Conversion rate as a fraction',
    type: 'number',
    typeDescription: 'Range: 0-1',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/goals/time-series',
            params={
                'goal_ids': '1,2',
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/goals/time-series?goal_ids=1,2&bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-01T00:00:00.000Z",
          "goal_id": 1,
          "conversions": 84,
          "total_sessions": 1250,
          "conversion_rate": 0.0672
        },
        {
          "time": "2024-01-02T00:00:00.000Z",
          "goal_id": 1,
          "conversions": 97,
          "total_sessions": 1420,
          "conversion_rate": 0.0683
        }
      ]
    }
    ```
  </div>
</div>


# Update Goal (/fr/docs/api/goals/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:site/goals/:goalId
    ```

    Updates an existing goal.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  goalId: {
    description: 'ID of the goal to update',
    type: 'string | number',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Updated goal name',
    type: 'string',
    required: false,
  },
  goalType: {
    description: 'Type of goal',
    type: 'string',
    typeDescription: '&#x22;path&#x22; | &#x22;event&#x22;',
    required: true,
  },
  config: {
    description: 'Updated goal configuration',
    type: 'GoalConfig',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the goal was updated',
    type: 'boolean',
  },
  goalId: {
    description: 'ID of the updated goal',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/sites/1/goals/123" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Signup Completed (Updated)",
            "goalType": "path",
            "config": {
              "pathPattern": "/signup/complete/*"
            }
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/goals/123',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Signup Completed (Updated)',
              goalType: 'path',
              config: {
                pathPattern: '/signup/complete/*'
              }
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/sites/1/goals/123',
            json={
                'name': 'Signup Completed (Updated)',
                'goalType': 'path',
                'config': {
                    'pathPattern': '/signup/complete/*'
                }
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Signup Completed (Updated)',
            'goalType' => 'path',
            'config' => [
                'pathPattern' => '/signup/complete/*'
            ]
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/goals/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/goals/123')
        request = Net::HTTP::Put.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Signup Completed (Updated)',
          goalType: 'path',
          config: { pathPattern: '/signup/complete/*' }
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Signup Completed (Updated)",
            "goalType": "path",
            "config": map[string]string{
                "pathPattern": "/signup/complete/*",
            },
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("PUT", "https://app.rybbit.io/api/sites/1/goals/123", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Signup Completed (Updated)",
            "goalType": "path",
            "config": {
                "pathPattern": "/signup/complete/*"
            }
        });

        let client = reqwest::Client::new();
        let res = client
            .put("https://app.rybbit.io/api/sites/1/goals/123")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Signup Completed (Updated)",
          "goalType": "path",
          "config": {
            "pathPattern": "/signup/complete/*"
          }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/goals/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Signup Completed (Updated)",
            goalType = "path",
            config = new { pathPattern = "/signup/complete/*" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PutAsync("https://app.rybbit.io/api/sites/1/goals/123", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "goalId": 1
    }
    ```
  </div>
</div>


# Create Import (/fr/docs/api/imports/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/imports
    ```

    Starts a new data import from a supported platform. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    Only one concurrent import is allowed per organization. Starting a second import while one is still running returns HTTP `429`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  platform: {
    description: 'Source platform to import data from',
    type: 'string',
    typeDescription: '&#x22;umami&#x22; | &#x22;simple_analytics&#x22; | &#x22;plausible&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Import details',
    type: 'CreateImportData',
  },
}"
    />

    #### CreateImportData Object [#createimportdata-object]

    <TypeTable
      type="{
  importId: {
    description: 'UUID of the created import. Use this when uploading events.',
    type: 'string',
    typeDescription: 'UUID',
  },
  allowedDateRange: {
    description: 'The inclusive date window you may import events within, based on your plan\'s retention',
    type: 'AllowedDateRange',
  },
}"
    />

    #### AllowedDateRange Object [#alloweddaterange-object]

    <TypeTable
      type="{
  earliestAllowedDate: {
    description: 'Earliest date you may import events for (inclusive)',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
  latestAllowedDate: {
    description: 'Latest date you may import events for (inclusive)',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/123/imports" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "platform": "plausible"
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              platform: 'plausible'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/123/imports',
            json={
                'platform': 'plausible'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'platform' => 'plausible'
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/imports')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          platform: 'plausible'
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "platform": "plausible",
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/123/imports", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "platform": "plausible"
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/123/imports")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "platform": "plausible"
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/imports"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            platform = "plausible"
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/123/imports", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "importId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "allowedDateRange": {
          "earliestAllowedDate": "2023-01-01",
          "latestAllowedDate": "2024-01-31"
        }
      }
    }
    ```
  </div>
</div>


# Delete Import (/fr/docs/api/imports/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/imports/:importId
    ```

    Deletes an import and all events it added. The import must be finished. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    A still-running import cannot be deleted and returns HTTP `400`.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  importId: {
    description: 'UUID of the import to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns `200 OK` with an empty body.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479')
        req = Net::HTTP::Delete.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479");
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Upload Import Events (/fr/docs/api/imports/events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/imports/:importId/events
    ```

    Uploads a batch of raw events to an in-progress import. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    Upload events in batches. The request body limit is 50 MB, so split large exports across multiple requests. Set `isLastBatch` to `true` on the final batch to finalize the import.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  importId: {
    description: 'UUID of the import to upload events to',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  events: {
    description: 'Raw, platform-specific event objects whose shape matches the platform chosen when the import was created (Umami, Simple Analytics, or Plausible export rows)',
    type: 'object[]',
    required: true,
  },
  isLastBatch: {
    description: 'Set to true on the final batch to finalize the import',
    type: 'boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns `200 OK` with an empty body. Events outside your plan's retention window are skipped and reflected in the import's `skippedEvents` / `invalidEvents` counts (see [List Imports](/docs/api/imports/list)).
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "events": [
              { "...": "platform-specific fields" }
            ],
            "isLastBatch": false
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              events: [
                { '...': 'platform-specific fields' }
              ],
              isLastBatch: false
            })
          }
        );
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events',
            json={
                'events': [
                    { '...': 'platform-specific fields' }
                ],
                'isLastBatch': False
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'events' => [
                ['...' => 'platform-specific fields']
            ],
            'isLastBatch' => false
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          events: [
            { '...': 'platform-specific fields' }
          ],
          isLastBatch: false
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "events": []map[string]string{
                {"...": "platform-specific fields"},
            },
            "isLastBatch": false,
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "events": [
                {"...": "platform-specific fields"}
            ],
            "isLastBatch": false
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "events": [
            {"...": "platform-specific fields"}
          ],
          "isLastBatch": false
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            events = new[]
            {
                new Dictionary<string, string> { { "...", "platform-specific fields" } }
            },
            isLastBatch = false
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/123/imports/f47ac10b-58cc-4372-a567-0e02b2c3d479/events", content);
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# List Imports (/fr/docs/api/imports/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/imports
    ```

    Returns all data imports for a site with their progress counts. Requires an admin or owner API key. On Rybbit Cloud, this requires a paid plan.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of import objects',
    type: 'Import[]',
  },
}"
    />

    #### Import Object [#import-object]

    <TypeTable
      type="{
  importId: {
    description: 'Unique import identifier',
    type: 'string',
    typeDescription: 'UUID',
  },
  platform: {
    description: 'Source platform the data was imported from',
    type: 'string',
    typeDescription: '&#x22;umami&#x22; | &#x22;simple_analytics&#x22; | &#x22;plausible&#x22;',
  },
  importedEvents: {
    description: 'Number of events successfully imported',
    type: 'number',
  },
  skippedEvents: {
    description: 'Number of events skipped (e.g. outside the retention window)',
    type: 'number',
  },
  invalidEvents: {
    description: 'Number of events rejected as invalid',
    type: 'number',
  },
  startedAt: {
    description: 'When the import started',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  completedAt: {
    description: 'When the import finished, or null while it is still running',
    type: 'string | null',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/imports" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/imports',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/imports',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        <?php
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/imports');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ?>
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'
        require 'uri'

        uri = URI('https://app.rybbit.io/api/sites/123/imports')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(req)
        end

        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        package main

        import (
            "encoding/json"
            "io"
            "net/http"
        )

        func main() {
            url := "https://app.rybbit.io/api/sites/123/imports"

            req, _ := http.NewRequest("GET", url, nil)
            req.Header.Add("Authorization", "Bearer your_api_key_here")

            client := &http.Client{}
            resp, _ := client.Do(req)
            defer resp.Body.Close()

            body, _ := io.ReadAll(resp.Body)

            var data map[string]interface{}
            json.Unmarshal(body, &data)
        }
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        use reqwest;
        use serde_json::Value;

        #[tokio::main]
        async fn main() -> Result<(), Box<dyn std::error::Error>> {
            let client = reqwest::Client::new();

            let response = client
                .get("https://app.rybbit.io/api/sites/123/imports")
                .header("Authorization", "Bearer your_api_key_here")
                .send()
                .await?;

            let data: Value = response.json().await?;

            Ok(())
        }
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class Main {
            public static void main(String[] args) throws Exception {
                HttpClient client = HttpClient.newHttpClient();

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://app.rybbit.io/api/sites/123/imports"))
                    .header("Authorization", "Bearer your_api_key_here")
                    .GET()
                    .build();

                HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

                String data = response.body();
            }
        }
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using System;
        using System.Net.Http;
        using System.Threading.Tasks;

        class Program
        {
            static async Task Main(string[] args)
            {
                using var client = new HttpClient();

                client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

                var response = await client.GetAsync(
                    "https://app.rybbit.io/api/sites/123/imports");

                var data = await response.Content.ReadAsStringAsync();
            }
        }
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "importId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
          "platform": "plausible",
          "importedEvents": 15420,
          "skippedEvents": 120,
          "invalidEvents": 3,
          "startedAt": "2024-01-10T12:00:00.000Z",
          "completedAt": "2024-01-10T12:04:30.000Z"
        },
        {
          "importId": "9a1c8f2e-3b7d-4e1a-9c0f-2d5b6a7e8f10",
          "platform": "umami",
          "importedEvents": 8200,
          "skippedEvents": 0,
          "invalidEvents": 0,
          "startedAt": "2024-01-15T09:30:00.000Z",
          "completedAt": null
        }
      ]
    }
    ```
  </div>
</div>


# Get Journeys (/fr/docs/api/insights/journeys)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/journeys
    ```

    Returns the most common page navigation paths (user journeys) within sessions. Useful for understanding how users navigate through your site.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  steps: {
    description: 'Maximum number of steps in the journey (2-10)',
    type: 'number',
    default: 3,
  },
  limit: {
    description: 'Maximum number of journeys to return (1-500)',
    type: 'number',
    default: 100,
  },
  stepFilters: {
    description: 'JSON object to filter specific steps (e.g., {&#x22;0&#x22;: &#x22;/&#x22;})',
    type: 'string',
    typeDescription: 'JSON string mapping step index to required path',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  journeys: {
    description: 'Array of journey objects',
    type: 'Journey[]',
  },
}"
    />

    #### Journey Object [#journey-object]

    <TypeTable
      type="{
  path: {
    description: 'Array of page paths in order',
    type: 'string[]',
  },
  count: {
    description: 'Number of sessions with this journey',
    type: 'number',
  },
  percentage: {
    description: 'Percentage of total sessions',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/journeys',
            params={
                'steps': 4,
                'limit': 20,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/journeys?steps=4&limit=20&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "journeys": [
        {
          "path": ["/", "/pricing", "/signup"],
          "count": 1250,
          "percentage": 8.12
        },
        {
          "path": ["/", "/features", "/pricing", "/signup"],
          "count": 890,
          "percentage": 5.78
        },
        {
          "path": ["/blog/getting-started", "/", "/pricing"],
          "count": 650,
          "percentage": 4.22
        },
        {
          "path": ["/", "/docs", "/docs/quickstart"],
          "count": 580,
          "percentage": 3.77
        },
        {
          "path": ["/", "/about", "/contact"],
          "count": 420,
          "percentage": 2.73
        }
      ]
    }
    ```

    ### Filtering by Step [#filtering-by-step]

    You can filter journeys that include specific pages at specific steps:

    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Filter journeys starting from homepage"
        curl -X GET "https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Filter journeys starting from homepage"
        const stepFilters = JSON.stringify({ "0": "/" });

        const response = await fetch(
          `https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=${encodeURIComponent(stepFilters)}`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/journeys?steps=3&stepFilters=%7B%220%22%3A%22%2F%22%7D");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response with step filter"
    {
      "journeys": [
        {
          "path": ["/", "/pricing", "/signup"],
          "count": 1250,
          "percentage": 12.5
        },
        {
          "path": ["/", "/features", "/pricing"],
          "count": 890,
          "percentage": 8.9
        },
        {
          "path": ["/", "/docs", "/docs/quickstart"],
          "count": 580,
          "percentage": 5.8
        }
      ]
    }
    ```
  </div>
</div>


# Get Retention (/fr/docs/api/insights/retention)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/retention
    ```

    Returns cohort-based retention analysis data. Users are grouped into cohorts based on their first visit, and retention is tracked over subsequent time periods.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  mode: {
    description: 'Retention period granularity',
    type: 'string',
    typeDescription: '&#x22;day&#x22; | &#x22;week&#x22;',
    default: 'week',
  },
  range: {
    description: 'Number of days to analyze (7-365)',
    type: 'number',
    default: 90,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Retention analysis data',
    type: 'RetentionData',
  },
}"
    />

    #### RetentionData Object [#retentiondata-object]

    <TypeTable
      type="{
  cohorts: {
    description: 'Map of cohort periods to retention data',
    type: 'Record<string, CohortData>',
  },
  maxPeriods: {
    description: 'Maximum number of retention periods',
    type: 'number',
  },
  mode: {
    description: 'Retention mode used',
    type: 'string',
    typeDescription: '&#x22;day&#x22; | &#x22;week&#x22;',
  },
  range: {
    description: 'Time range in days',
    type: 'number',
  },
}"
    />

    #### CohortData Object [#cohortdata-object]

    <TypeTable
      type="{
  size: {
    description: 'Number of users in the cohort',
    type: 'number',
  },
  percentages: {
    description: 'Retention percentages for each period (index 0 = period 0, etc.)',
    type: '(number | null)[]',
    typeDescription: 'null indicates no data for that period yet',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/retention?mode=week&range=90" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/retention?mode=week&range=90',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/retention',
            params={
                'mode': 'week',
                'range': 90
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/retention?mode=week&range=90');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/retention?mode=week&range=90')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/retention?mode=week&range=90", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/retention?mode=week&range=90");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "cohorts": {
          "2024-01-01": {
            "size": 1250,
            "percentages": [100, 45.2, 32.1, 28.5, 25.3, 22.1]
          },
          "2024-01-08": {
            "size": 1420,
            "percentages": [100, 48.5, 35.2, 30.1, 26.8, null]
          },
          "2024-01-15": {
            "size": 1380,
            "percentages": [100, 46.8, 33.5, 29.2, null, null]
          },
          "2024-01-22": {
            "size": 1510,
            "percentages": [100, 44.2, 31.8, null, null, null]
          },
          "2024-01-29": {
            "size": 1290,
            "percentages": [100, 47.1, null, null, null, null]
          }
        },
        "maxPeriods": 5,
        "mode": "week",
        "range": 90
      }
    }
    ```

    ### Understanding Retention Data [#understanding-retention-data]

    The retention data shows how many users from each cohort return in subsequent periods:

    * **Period 0**: Always 100% (the cohort's first visit)
    * **Period 1**: Users who returned 1 week later
    * **Period 2**: Users who returned 2 weeks later
    * etc.

    A `null` value indicates that period hasn't occurred yet for that cohort.

    ### Visualization Example [#visualization-example]

    ```javascript title="Building a Retention Table"
    const { cohorts, maxPeriods } = data.data;

    // Headers: Cohort, Size, Week 0, Week 1, Week 2, ...
    const headers = ['Cohort', 'Size',
      ...Array(maxPeriods + 1).fill(0).map((_, i) => `Week ${i}`)
    ];

    // Rows
    Object.entries(cohorts).forEach(([date, cohort]) => {
      const row = [
        date,
        cohort.size,
        ...cohort.percentages.map(p => p !== null ? `${p}%` : '-')
      ];
      console.log(row.join(' | '));
    });
    ```
  </div>
</div>


# Add Organization Member (/fr/docs/api/organizations/add-member)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/members
    ```

    Adds a user to an organization with a specified role. The user must already exist in the system. Requires admin or owner role in the organization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  email: {
    description: 'Email address of the user to add',
    type: 'string',
    typeDescription: 'Must match an existing user',
    required: true,
  },
  role: {
    description: 'Role to assign to the user',
    type: 'string',
    typeDescription: '&#x22;admin&#x22; | &#x22;member&#x22; | &#x22;owner&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns a success message when the user is added successfully.

    <TypeTable
      type="{
  message: {
    description: 'Success message',
    type: 'string',
  },
}"
    />

    ### Error Responses [#error-responses]

    <TypeTable
      type="{
  '400': {
    description: 'Invalid input (missing fields, invalid role, or user already a member)',
    type: 'object',
  },
  '401': {
    description: 'Unauthorized (not an admin/owner of the organization)',
    type: 'object',
  },
  '404': {
    description: 'User not found',
    type: 'object',
  },
  '500': {
    description: 'Internal server error',
    type: 'object',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_123/members" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"email": "newuser@example.com", "role": "member"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/members`,
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              email: 'newuser@example.com',
              role: 'member'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_123'
        response = requests.post(
            f'https://app.rybbit.io/api/organizations/{organization_id}/members',
            json={
                'email': 'newuser@example.com',
                'role': 'member'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/members");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'email' => 'newuser@example.com',
            'role' => 'member'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/members")
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = {
          email: 'newuser@example.com',
          role: 'member'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_123"
        body := bytes.NewBuffer([]byte(`{
          "email": "newuser@example.com",
          "role": "member"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/"+organizationId+"/members", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_123";
        let client = reqwest::Client::new();
        let res = client
            .post(format!("https://app.rybbit.io/api/organizations/{}/members", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "email": "newuser@example.com",
                "role": "member"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_123";
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"email\": \"newuser@example.com\", \"role\": \"member\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/members"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"email\": \"newuser@example.com\", \"role\": \"member\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"https://app.rybbit.io/api/organizations/{organizationId}/members", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "message": "User added to organization successfully"
    }
    ```

    ```json title="Error Response (400 - Already a Member)"
    {
      "error": "User is already a member of this organization"
    }
    ```

    ```json title="Error Response (404 - User Not Found)"
    {
      "error": "User not found"
    }
    ```

    ```json title="Error Response (401 - Unauthorized)"
    {
      "error": "Unauthorized"
    }
    ```
  </div>
</div>


# Create Site (/fr/docs/api/organizations/create-site)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/sites
    ```

    Creates a new site within an organization. Requires admin or owner role in the organization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID to add the site to',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  domain: {
    description: 'Site domain',
    type: 'string',
    typeDescription: 'Valid domain format (e.g., example.com)',
    required: true,
  },
  name: {
    description: 'Site display name',
    type: 'string',
    required: true,
  },
  public: {
    description: 'Make analytics publicly accessible',
    type: 'boolean',
    default: false,
  },
  saltUserIds: {
    description: 'Salt user IDs for privacy',
    type: 'boolean',
    default: false,
  },
  blockBots: {
    description: 'Block bot traffic',
    type: 'boolean',
    default: true,
  },
  excludedIPs: {
    description: 'Array of IP addresses to exclude from tracking',
    type: 'string[]',
    default: '[]',
  },
  excludedCountries: {
    description: 'Array of ISO country codes to exclude (e.g., [&#x22;US&#x22;, &#x22;GB&#x22;])',
    type: 'string[]',
    default: '[]',
  },
  sessionReplay: {
    description: 'Enable session replay recording',
    type: 'boolean',
    default: false,
  },
  webVitals: {
    description: 'Enable Core Web Vitals tracking',
    type: 'boolean',
    default: false,
  },
  trackErrors: {
    description: 'Enable JavaScript error tracking',
    type: 'boolean',
    default: false,
  },
  trackOutbound: {
    description: 'Track outbound link clicks',
    type: 'boolean',
    default: true,
  },
  trackUrlParams: {
    description: 'Track URL parameters (UTM, etc.)',
    type: 'boolean',
    default: true,
  },
  trackInitialPageView: {
    description: 'Automatically track the initial page view',
    type: 'boolean',
    default: true,
  },
  trackSpaNavigation: {
    description: 'Track SPA navigation events',
    type: 'boolean',
    default: true,
  },
  trackIp: {
    description: 'Store visitor IP addresses',
    type: 'boolean',
    default: false,
  },
  trackButtonClicks: {
    description: 'Track button click events',
    type: 'boolean',
    default: false,
  },
  trackCopy: {
    description: 'Track copy events',
    type: 'boolean',
    default: false,
  },
  trackFormInteractions: {
    description: 'Track form interaction events',
    type: 'boolean',
    default: false,
  },
  tags: {
    description: 'Array of tags for organizing the site',
    type: 'string[]',
    default: '[]',
  },
}"
    />

    ### Response [#response]

    Returns the created site object with the assigned `siteId`.

    <TypeTable
      type="{
  siteId: {
    description: 'Numeric site ID (auto-assigned)',
    type: 'number',
  },
  id: {
    description: 'Site UUID',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string',
  },
  createdBy: {
    description: 'User ID who created the site',
    type: 'string',
  },
  public: {
    description: 'Whether analytics are public',
    type: 'boolean',
  },
  saltUserIds: {
    description: 'Whether user IDs are salted',
    type: 'boolean',
  },
  blockBots: {
    description: 'Whether bot traffic is blocked',
    type: 'boolean',
  },
  excludedIPs: {
    description: 'Excluded IP addresses',
    type: 'string[]',
  },
  excludedCountries: {
    description: 'Excluded country codes',
    type: 'string[]',
  },
  sessionReplay: {
    description: 'Whether session replay is enabled',
    type: 'boolean',
  },
  webVitals: {
    description: 'Whether Web Vitals tracking is enabled',
    type: 'boolean',
  },
  trackErrors: {
    description: 'Whether error tracking is enabled',
    type: 'boolean',
  },
  trackOutbound: {
    description: 'Whether outbound link tracking is enabled',
    type: 'boolean',
  },
  trackUrlParams: {
    description: 'Whether URL parameter tracking is enabled',
    type: 'boolean',
  },
  trackInitialPageView: {
    description: 'Whether initial page view is tracked automatically',
    type: 'boolean',
  },
  trackSpaNavigation: {
    description: 'Whether SPA navigation is tracked',
    type: 'boolean',
  },
  trackIp: {
    description: 'Whether IP addresses are stored',
    type: 'boolean',
  },
  trackButtonClicks: {
    description: 'Whether button clicks are tracked',
    type: 'boolean',
  },
  trackCopy: {
    description: 'Whether copy events are tracked',
    type: 'boolean',
  },
  trackFormInteractions: {
    description: 'Whether form interactions are tracked',
    type: 'boolean',
  },
  tags: {
    description: 'Site tags',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_123/sites" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"domain": "example.com", "name": "My Website", "blockBots": true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/sites`,
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              domain: 'example.com',
              name: 'My Website',
              blockBots: true
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_123'
        response = requests.post(
            f'https://app.rybbit.io/api/organizations/{organization_id}/sites',
            json={
                'domain': 'example.com',
                'name': 'My Website',
                'blockBots': True
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/sites");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'domain' => 'example.com',
            'name' => 'My Website',
            'blockBots' => true
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/sites")
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = {
          domain: 'example.com',
          name: 'My Website',
          blockBots: true
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_123"
        body := bytes.NewBuffer([]byte(`{
          "domain": "example.com",
          "name": "My Website",
          "blockBots": true
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/"+organizationId+"/sites", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_123";
        let client = reqwest::Client::new();
        let res = client
            .post(format!("https://app.rybbit.io/api/organizations/{}/sites", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "domain": "example.com",
                "name": "My Website",
                "blockBots": true
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_123";
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"domain\": \"example.com\", \"name\": \"My Website\", \"blockBots\": true}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/sites"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"domain\": \"example.com\", \"name\": \"My Website\", \"blockBots\": true}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"https://app.rybbit.io/api/organizations/{organizationId}/sites", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "siteId": 456,
      "id": "a1b2c3d4e5f6",
      "domain": "example.com",
      "name": "My Website",
      "organizationId": "org_123",
      "createdBy": "user_xyz789",
      "public": false,
      "saltUserIds": false,
      "blockBots": true,
      "excludedIPs": [],
      "excludedCountries": [],
      "sessionReplay": false,
      "webVitals": false,
      "trackErrors": false,
      "trackOutbound": true,
      "trackUrlParams": true,
      "trackInitialPageView": true,
      "trackSpaNavigation": true,
      "trackIp": false,
      "trackButtonClicks": false,
      "trackCopy": false,
      "trackFormInteractions": false,
      "tags": []
    }
    ```
  </div>
</div>


# Get Organization Event Count (/fr/docs/api/organizations/event-count)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/org-event-count/:organizationId
    ```

    Returns daily event usage counts across an organization's sites.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  start_date: {
    description: 'Start of the date range. Omit start/end to get all-time daily counts.',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
  end_date: {
    description: 'End of the date range. Omit start/end to get all-time daily counts.',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
  },
  time_zone: {
    description: 'IANA timezone used to bucket events into days',
    type: 'string',
    default: 'UTC',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  event_date: {
    description: 'The day the counts apply to',
    type: 'string',
  },
  pageview_count: {
    description: 'Number of pageview events',
    type: 'number',
  },
  custom_event_count: {
    description: 'Number of custom events',
    type: 'number',
  },
  performance_count: {
    description: 'Number of performance events',
    type: 'number',
  },
  outbound_count: {
    description: 'Number of outbound link events',
    type: 'number',
  },
  error_count: {
    description: 'Number of error events',
    type: 'number',
  },
  button_click_count: {
    description: 'Number of button click events',
    type: 'number',
  },
  copy_count: {
    description: 'Number of copy events',
    type: 'number',
  },
  form_submit_count: {
    description: 'Number of form submit events',
    type: 'number',
  },
  input_change_count: {
    description: 'Number of input change events',
    type: 'number',
  },
  event_count: {
    description: 'Total number of events for the day',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/org-event-count/org_abc123?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/org-event-count/${organizationId}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.get(
            f'https://app.rybbit.io/api/org-event-count/{organization_id}',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'UTC'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/org-event-count/{$organizationId}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/org-event-count/#{organization_id}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/org-event-count/"+organizationId+"?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/org-event-count/{}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/org-event-count/" + organizationId + "?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/org-event-count/{organizationId}?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "event_date": "2024-01-01",
          "pageview_count": 38900,
          "custom_event_count": 4210,
          "performance_count": 12050,
          "outbound_count": 980,
          "error_count": 145,
          "button_click_count": 6320,
          "copy_count": 410,
          "form_submit_count": 220,
          "input_change_count": 1530,
          "event_count": 64765
        },
        {
          "event_date": "2024-01-02",
          "pageview_count": 41200,
          "custom_event_count": 4560,
          "performance_count": 12880,
          "outbound_count": 1040,
          "error_count": 132,
          "button_click_count": 6710,
          "copy_count": 455,
          "form_submit_count": 248,
          "input_change_count": 1622,
          "event_count": 68847
        }
      ]
    }
    ```
  </div>
</div>


# Invite Member (/fr/docs/api/organizations/invite-member)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/organization/invite-member
    ```

    Sends an invitation email inviting a user to join an organization with a given role. (To add an existing user directly without an email invite, see Add Member.)

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  email: {
    description: 'Email address of the user to invite',
    type: 'string',
    required: true,
  },
  role: {
    description: 'Role(s) to assign. One of `owner`, `admin`, `member` (or an array of roles).',
    type: 'string | string[]',
    required: true,
  },
  organizationId: {
    description: 'The organization to invite into. Defaults to your active organization.',
    type: 'string',
    required: false,
  },
  resend: {
    description: 'Resend the invitation if the user was already invited.',
    type: 'boolean',
    required: false,
  },
  teamId: {
    description: 'Team ID(s) to add the invited user to.',
    type: 'string | string[]',
    required: false,
  },
  hasRestrictedSiteAccess: {
    description: 'Rybbit extension: restrict the invited member to specific sites. Only valid when role is `member`.',
    type: 'boolean',
    required: false,
  },
  siteIds: {
    description: 'Rybbit extension: the site IDs the member may access when `hasRestrictedSiteAccess` is true.',
    type: 'number[]',
    required: false,
  },
}"
    />

    <Callout>
      `hasRestrictedSiteAccess`

       and 

      `siteIds`

       are Rybbit-specific extensions to the invitation. Site-access restrictions can only be applied to invitations with the 

      `member`

       role.
    </Callout>

    ### Response [#response]

    Returns the created invitation object.

    <TypeTable
      type="{
  id: {
    description: &#x22;The invitation's identifier&#x22;,
    type: 'string',
  },
  email: {
    description: 'Invited email address',
    type: 'string',
  },
  role: {
    description: 'Assigned role',
    type: 'string',
  },
  organizationId: {
    description: 'The organization the invite is for',
    type: 'string',
  },
  inviterId: {
    description: 'ID of the user who sent the invite',
    type: 'string',
  },
  status: {
    description: 'Invitation status (e.g. pending)',
    type: 'string',
  },
  expiresAt: {
    description: 'When the invitation expires',
    type: 'string',
  },
  hasRestrictedSiteAccess: {
    description: 'Whether the member will be restricted to specific sites',
    type: 'boolean',
  },
  siteIds: {
    description: 'Site IDs the member will be allowed to access',
    type: 'number[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/organization/invite-member" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"email": "teammate@example.com", "role": "member"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/organization/invite-member',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              email: 'teammate@example.com',
              role: 'member'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/organization/invite-member',
            json={
                'email': 'teammate@example.com',
                'role': 'member'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/organization/invite-member");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'email' => 'teammate@example.com',
            'role' => 'member'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/organization/invite-member")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          email: 'teammate@example.com',
          role: 'member'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "email": "teammate@example.com",
          "role": "member"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/organization/invite-member", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/organization/invite-member")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "email": "teammate@example.com",
                "role": "member"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"email\": \"teammate@example.com\", \"role\": \"member\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/organization/invite-member"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"email\": \"teammate@example.com\", \"role\": \"member\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/organization/invite-member", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "inv_4a2b...",
      "email": "teammate@example.com",
      "role": "member",
      "organizationId": "org_123",
      "inviterId": "user_2a9b...",
      "status": "pending",
      "expiresAt": "2026-07-03T12:00:00.000Z",
      "hasRestrictedSiteAccess": false,
      "siteIds": []
    }
    ```
  </div>
</div>


# Get My Organizations (/fr/docs/api/organizations/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations
    ```

    Returns all organizations the authenticated user is a member of, including all members for each organization. Excludes subscription and billing information. Supports both session cookies and API key (Bearer token) authentication.

    <Callout type="warn">
      The 

      `members`

       roster is only populated for session-cookie (dashboard) requests. API key / Bearer callers receive 

      `members: []`

       for every organization — use 

      [GET /organizations/:id/members](/docs/api/organizations/members)

       to retrieve member data with a key.
    </Callout>

    ### Response [#response]

    Returns an array of organization objects.

    <TypeTable
      type="{
  id: {
    description: 'Organization ID',
    type: 'string',
  },
  name: {
    description: 'Organization name',
    type: 'string',
  },
  slug: {
    description: 'Organization slug',
    type: 'string',
  },
  logo: {
    description: 'Organization logo URL',
    type: 'string | null',
  },
  createdAt: {
    description: 'Organization creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  role: {
    description: 'Your role in the organization',
    type: 'string',
    typeDescription: '&#x22;owner&#x22; | &#x22;admin&#x22; | &#x22;member&#x22;',
  },
  members: {
    description: 'Array of organization members',
    type: 'array',
  },
  sites: {
    description: 'Array of sites in the organization',
    type: 'array',
  },
}"
    />

    #### Member Object [#member-object]

    Each member in the `members` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Member record ID',
    type: 'string',
  },
  role: {
    description: 'Member role in the organization',
    type: 'string',
    typeDescription: '&#x22;owner&#x22; | &#x22;admin&#x22; | &#x22;member&#x22;',
  },
  userId: {
    description: 'User ID',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when member was added',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  user: {
    description: 'User details',
    type: 'object',
  },
}"
    />

    #### User Object [#user-object]

    <TypeTable
      type="{
  id: {
    description: 'User ID',
    type: 'string',
  },
  name: {
    description: 'User display name',
    type: 'string',
  },
  email: {
    description: 'User email address',
    type: 'string',
  },
}"
    />

    #### Site Object [#site-object]

    Each site in the `sites` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Site ID',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string',
  },
  createdBy: {
    description: 'User ID who created the site',
    type: 'string',
  },
  public: {
    description: 'Whether analytics are publicly accessible',
    type: 'boolean',
  },
  saltUserIds: {
    description: 'Whether user IDs are salted',
    type: 'boolean',
  },
  blockBots: {
    description: 'Whether bot traffic is blocked',
    type: 'boolean',
  },
  createdAt: {
    description: 'Site creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/organizations',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/organizations')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data []map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/organizations")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/organizations");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    [
      {
        "id": "org_123",
        "name": "Acme Inc",
        "slug": "acme-inc",
        "logo": "https://example.com/logo.png",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "role": "owner",
        "members": [
          {
            "id": "member_abc123",
            "role": "owner",
            "userId": "user_xyz789",
            "createdAt": "2024-01-15T10:30:00.000Z",
            "user": {
              "id": "user_xyz789",
              "name": "John Doe",
              "email": "john@example.com"
            }
          },
          {
            "id": "member_def456",
            "role": "member",
            "userId": "user_abc456",
            "createdAt": "2024-02-20T14:15:00.000Z",
            "user": {
              "id": "user_abc456",
              "name": "Jane Smith",
              "email": "jane@example.com"
            }
          }
        ],
        "sites": [
          {
            "id": "456",
            "domain": "example.com",
            "name": "My Website",
            "organizationId": "org_123",
            "createdBy": "user_xyz789",
            "public": false,
            "saltUserIds": false,
            "blockBots": true,
            "createdAt": "2024-01-15T10:30:00.000Z"
          }
        ]
      },
      {
        "id": "org_456",
        "name": "Tech Startup",
        "slug": "tech-startup",
        "logo": null,
        "createdAt": "2024-03-10T08:00:00.000Z",
        "role": "admin",
        "members": [
          {
            "id": "member_ghi789",
            "role": "owner",
            "userId": "user_owner123",
            "createdAt": "2024-03-10T08:00:00.000Z",
            "user": {
              "id": "user_owner123",
              "name": "Alice Johnson",
              "email": "alice@techstartup.com"
            }
          },
          {
            "id": "member_jkl012",
            "role": "admin",
            "userId": "user_xyz789",
            "createdAt": "2024-03-12T09:30:00.000Z",
            "user": {
              "id": "user_xyz789",
              "name": "John Doe",
              "email": "john@example.com"
            }
          }
        ],
        "sites": [
          {
            "id": "789",
            "domain": "techstartup.com",
            "name": "Tech Startup Website",
            "organizationId": "org_456",
            "createdBy": "user_owner123",
            "public": true,
            "saltUserIds": false,
            "blockBots": true,
            "createdAt": "2024-03-10T08:00:00.000Z"
          }
        ]
      }
    ]
    ```
  </div>
</div>


# Get Organization Members (/fr/docs/api/organizations/members)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations/:organizationId/members
    ```

    Returns all members of an organization with their user details and roles. Requires membership in the organization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  data: {
    description: 'Array of organization members',
    type: 'array',
  },
}"
    />

    #### Member Object [#member-object]

    Each member in the `data` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Member record ID',
    type: 'string',
  },
  role: {
    description: 'Member role in the organization',
    type: 'string',
    typeDescription: '&#x22;owner&#x22; | &#x22;admin&#x22; | &#x22;member&#x22;',
  },
  userId: {
    description: 'User ID',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when member was added',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  user: {
    description: 'User details',
    type: 'object',
  },
  siteAccess: {
    description: &#x22;The member's site-access restrictions within the organization&#x22;,
    type: 'object',
  },
  teams: {
    description: 'Teams the member belongs to',
    type: 'array',
  },
}"
    />

    #### User Object [#user-object]

    <TypeTable
      type="{
  id: {
    description: 'User ID',
    type: 'string',
  },
  name: {
    description: 'User display name',
    type: 'string',
  },
  email: {
    description: 'User email address',
    type: 'string',
  },
}"
    />

    #### Site Access Object [#site-access-object]

    <TypeTable
      type="{
  hasRestrictedSiteAccess: {
    description: 'Whether the member is restricted to specific sites',
    type: 'boolean',
  },
  siteIds: {
    description: 'IDs of the sites the member can access (empty when access is not restricted)',
    type: 'array',
  },
}"
    />

    #### Team Object [#team-object]

    Each team in the `teams` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Team ID',
    type: 'string',
  },
  name: {
    description: 'Team name',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations/org_123/members" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/members`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_123'
        response = requests.get(
            f'https://app.rybbit.io/api/organizations/{organization_id}/members',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/members");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/members")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations/"+organizationId+"/members", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/organizations/{}/members", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/members"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/organizations/{organizationId}/members");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": [
        {
          "id": "member_abc123",
          "role": "owner",
          "userId": "user_xyz789",
          "organizationId": "org_123",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "user": {
            "id": "user_xyz789",
            "name": "John Doe",
            "email": "john@example.com"
          },
          "siteAccess": {
            "hasRestrictedSiteAccess": false,
            "siteIds": []
          },
          "teams": []
        },
        {
          "id": "member_def456",
          "role": "member",
          "userId": "user_abc456",
          "organizationId": "org_123",
          "createdAt": "2024-02-20T14:15:00.000Z",
          "user": {
            "id": "user_abc456",
            "name": "Jane Smith",
            "email": "jane@example.com"
          },
          "siteAccess": {
            "hasRestrictedSiteAccess": true,
            "siteIds": ["456"]
          },
          "teams": [
            {
              "id": "team_789",
              "name": "Marketing"
            }
          ]
        }
      ]
    }
    ```
  </div>
</div>


# Remove Member (/fr/docs/api/organizations/remove-member)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/organization/remove-member
    ```

    Removes a member from an organization. The member can be identified by member ID or email.

    <Callout type="warn">
      This endpoint uses 

      **POST**

      , not HTTP DELETE. You cannot remove the only remaining owner of an organization.
    </Callout>

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  memberIdOrEmail: {
    description: &#x22;The member's ID or email address&#x22;,
    type: 'string',
    required: true,
  },
  organizationId: {
    description: 'The organization to remove from. Defaults to your active organization.',
    type: 'string',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the removed member object.

    <TypeTable
      type="{
  member: {
    description: 'The member that was removed',
    type: 'Member',
  },
}"
    />

    #### Member Object [#member-object]

    <TypeTable
      type="{
  id: {
    description: &#x22;The member record's identifier&#x22;,
    type: 'string',
  },
  userId: {
    description: &#x22;The underlying user's ID&#x22;,
    type: 'string',
  },
  organizationId: {
    description: 'The organization the member belonged to',
    type: 'string',
  },
  role: {
    description: &#x22;The member's role&#x22;,
    type: 'string',
  },
  createdAt: {
    description: 'When the membership was created',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/organization/remove-member" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"memberIdOrEmail": "teammate@example.com"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/organization/remove-member',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              memberIdOrEmail: 'teammate@example.com'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/organization/remove-member',
            json={
                'memberIdOrEmail': 'teammate@example.com'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/organization/remove-member");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'memberIdOrEmail' => 'teammate@example.com'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/organization/remove-member")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          memberIdOrEmail: 'teammate@example.com'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "memberIdOrEmail": "teammate@example.com"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/organization/remove-member", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/organization/remove-member")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "memberIdOrEmail": "teammate@example.com"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"memberIdOrEmail\": \"teammate@example.com\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/organization/remove-member"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"memberIdOrEmail\": \"teammate@example.com\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/organization/remove-member", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "member": {
        "id": "mem_7c6d...",
        "userId": "user_5f4g...",
        "organizationId": "org_123",
        "role": "member",
        "createdAt": "2026-01-10T12:00:00.000Z"
      }
    }
    ```
  </div>
</div>


# Get Organization Sites (/fr/docs/api/organizations/sites)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations/:organizationId/sites
    ```

    Returns all sites in an organization the caller can access, with usage and subscription info.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  organization: {
    description: 'The organization record, or null',
    type: 'object | null',
  },
  sites: {
    description: 'Array of site objects',
    type: 'array',
  },
  subscription: {
    description: 'Usage and subscription details for the organization',
    type: 'object',
  },
}"
    />

    #### Site Object [#site-object]

    Each site in the `sites` array contains the following fields. Other site-config fields may also be present:

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'number',
  },
  name: {
    description: 'Site display name',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  type: {
    description: 'Site type',
    type: 'string',
    typeDescription: 'e.g. &#x22;web&#x22;',
  },
  public: {
    description: 'Whether the site dashboard is public',
    type: 'boolean',
  },
  organizationId: {
    description: 'Organization ID the site belongs to',
    type: 'string',
  },
  sessionsLast24Hours: {
    description: 'Number of sessions in the last 24 hours',
    type: 'number',
  },
  isOwner: {
    description: 'Whether the caller owns the site',
    type: 'boolean',
  },
  teams: {
    description: 'Teams the site belongs to',
    type: 'array',
    typeDescription: 'Array of { id, name }',
  },
}"
    />

    #### Subscription Object [#subscription-object]

    <TypeTable
      type="{
  monthlyEventCount: {
    description: 'Events recorded in the current month',
    type: 'number',
  },
  eventLimit: {
    description: 'Monthly event limit for the plan',
    type: 'number',
  },
  overMonthlyLimit: {
    description: 'Whether the monthly event limit has been exceeded',
    type: 'boolean',
  },
  planName: {
    description: 'Name of the active plan',
    type: 'string',
  },
  status: {
    description: 'Subscription status',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations/org_abc123/sites" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/sites`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.get(
            f'https://app.rybbit.io/api/organizations/{organization_id}/sites',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/sites");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/sites")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations/"+organizationId+"/sites", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/organizations/{}/sites", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/sites"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/organizations/{organizationId}/sites");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "organization": {
        "id": "org_abc123",
        "name": "Acme Inc",
        "slug": "acme",
        "createdAt": "2024-01-15T10:30:00.000Z"
      },
      "sites": [
        {
          "siteId": 123,
          "name": "Acme Marketing",
          "domain": "acme.com",
          "type": "web",
          "public": false,
          "organizationId": "org_abc123",
          "sessionsLast24Hours": 842,
          "isOwner": true,
          "teams": [
            {
              "id": "team_xyz789",
              "name": "Growth"
            }
          ]
        }
      ],
      "subscription": {
        "monthlyEventCount": 482910,
        "eventLimit": 1000000,
        "overMonthlyLimit": false,
        "planName": "Pro",
        "status": "active"
      }
    }
    ```
  </div>
</div>


# Update Member Role (/fr/docs/api/organizations/update-member-role)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/auth/organization/update-member-role
    ```

    Updates the role(s) assigned to an existing organization member.

    <Callout>
      This endpoint uses 

      **POST**

      , not PUT or PATCH.
    </Callout>

    <Callout type="warn">
      This endpoint authenticates with your logged-in dashboard 

      **session**

      , not an API key. Send your session cookie with the request.
    </Callout>

    ### Request Body [#request-body]

    <TypeTable
      type="{
  role: {
    description: 'The new role(s) to assign. One of `owner`, `admin`, `member` (or an array of roles).',
    type: 'string | string[]',
    required: true,
  },
  memberId: {
    description: 'The ID of the member to update',
    type: 'string',
    required: true,
  },
  organizationId: {
    description: 'The organization the member belongs to. Defaults to your active organization.',
    type: 'string',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the updated member object directly — the fields are at the top level, **not** nested under a `member` key.

    <TypeTable
      type="{
  id: {
    description: &#x22;The member record's identifier&#x22;,
    type: 'string',
  },
  userId: {
    description: &#x22;The underlying user's ID&#x22;,
    type: 'string',
  },
  organizationId: {
    description: 'The organization the member belongs to',
    type: 'string',
  },
  role: {
    description: &#x22;The member's updated role&#x22;,
    type: 'string',
  },
  createdAt: {
    description: 'When the membership was created',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/auth/organization/update-member-role" \
          -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{"memberId": "mem_7c6d5e4f3g2h", "role": "admin"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/auth/organization/update-member-role',
          {
            method: 'POST',
            credentials: 'include',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              memberId: 'mem_7c6d5e4f3g2h',
              role: 'admin'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/auth/organization/update-member-role',
            json={
                'memberId': 'mem_7c6d5e4f3g2h',
                'role': 'admin'
            },
            headers={
                'Cookie': 'better-auth.session_token=YOUR_SESSION_TOKEN'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/auth/organization/update-member-role");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'memberId' => 'mem_7c6d5e4f3g2h',
            'role' => 'admin'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Cookie: better-auth.session_token=YOUR_SESSION_TOKEN',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI("https://app.rybbit.io/api/auth/organization/update-member-role")
        req = Net::HTTP::Post.new(uri)
        req['Cookie'] = 'better-auth.session_token=YOUR_SESSION_TOKEN'
        req['Content-Type'] = 'application/json'
        req.body = {
          memberId: 'mem_7c6d5e4f3g2h',
          role: 'admin'
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{
          "memberId": "mem_7c6d5e4f3g2h",
          "role": "admin"
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/auth/organization/update-member-role", body)
        req.Header.Set("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/auth/organization/update-member-role")
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .json(&serde_json::json!({
                "memberId": "mem_7c6d5e4f3g2h",
                "role": "admin"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"memberId\": \"mem_7c6d5e4f3g2h\", \"role\": \"admin\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/auth/organization/update-member-role"))
            .header("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Cookie", "better-auth.session_token=YOUR_SESSION_TOKEN");

        var content = new StringContent(
            "{\"memberId\": \"mem_7c6d5e4f3g2h\", \"role\": \"admin\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/auth/organization/update-member-role", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "mem_7c6d5e4f3g2h",
      "userId": "user_5f4g...",
      "organizationId": "org_123",
      "role": "admin",
      "createdAt": "2026-01-10T12:00:00.000Z"
    }
    ```
  </div>
</div>


# Get Live Visitors (/fr/docs/api/overview/live-visitors)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/live-user-count
    ```

    Returns the count of unique active visitors within the specified time window. Useful for displaying real-time visitor counts.

    Visitors are counted by identity where one is available (see [Identify Users](/docs/identify-users)) and by anonymous device otherwise, so one person who starts a second session inside the window still counts once.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  minutes: {
    description: 'Time window in minutes to count active visitors',
    type: 'number',
    default: 5,
    typeDescription: 'Visitors with activity within the last N minutes are considered &#x22;live&#x22;',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  count: {
    description: 'Number of unique active visitors',
    type: 'number',
  },
}"
    />

    #### Time Window Guide [#time-window-guide]

    | Minutes | Use Case                                  |
    | ------- | ----------------------------------------- |
    | `1`     | Very active visitors (currently browsing) |
    | `5`     | Standard "live" count (default)           |
    | `15`    | Recently active visitors                  |
    | `30`    | Short-term engagement window              |
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/live-user-count?minutes=5" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/live-user-count?minutes=5',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const { count } = await response.json();
        console.log(`Live visitors: ${count}`);
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/live-user-count',
            params={'minutes': 5},
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        print(f"Live visitors: {data['count']}")
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/live-user-count?minutes=5');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        echo "Live visitors: " . $data['count'];
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/live-user-count?minutes=5')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        puts "Live visitors: #{data['count']}"
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/live-user-count?minutes=5", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        fmt.Printf("Live visitors: %v\n", data["count"])
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/live-user-count?minutes=5")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        println!("Live visitors: {}", data["count"]);
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/live-user-count?minutes=5"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/live-user-count?minutes=5");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "count": 42
    }
    ```

    ### Polling Example [#polling-example]

    ```javascript title="Real-time Widget"
    async function updateLiveCount() {
      const response = await fetch(
        'https://app.rybbit.io/api/sites/123/live-user-count?minutes=5',
        {
          headers: {
            'Authorization': 'Bearer your_api_key'
          }
        }
      );
      const { count } = await response.json();
      document.getElementById('live-visitors')
        .textContent = count;
    }

    // Update every 15 seconds
    setInterval(updateLiveCount, 15000);
    ```
  </div>
</div>


# Get Metric (/fr/docs/api/overview/metric)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/metric
    ```

    Returns dimensional analytics data broken down by a specific parameter. Supports pagination.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  parameter: {
    description: 'The dimension to break down by',
    type: 'FilterParameter',
    typeDescription: 'e.g., &#x22;pathname&#x22;, &#x22;country&#x22;, &#x22;browser&#x22;, &#x22;event_name&#x22;',
    required: true,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of metric results',
    type: 'MetricItem[]',
    typeDescription: 'See MetricItem structure below',
  },
  totalCount: {
    description: 'Total number of unique values across all pages',
    type: 'number',
  },
}"
    />

    #### MetricItem Structure [#metricitem-structure]

    <TypeTable
      type="{
  value: {
    description: 'The dimension value',
    type: 'string',
    typeDescription: 'e.g., &#x22;/blog&#x22;, &#x22;Chrome&#x22;, &#x22;US&#x22;',
  },
  count: {
    description: 'Number of unique sessions for this value. For parameter=event_name, this is the total number of event occurrences instead',
    type: 'number',
  },
  percentage: {
    description: 'Percentage of total sessions',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  pageviews: {
    description: 'Total pageviews (for page-related parameters)',
    type: 'number',
    required: false,
  },
  pageviews_percentage: {
    description: 'Share of total pageviews (for page-related parameters)',
    type: 'number',
    typeDescription: 'Range: 0-100',
    required: false,
  },
  bounce_rate: {
    description: 'Bounce rate percentage',
    type: 'number',
    typeDescription: 'Range: 0-100',
    required: false,
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/metric',
            params={
                'parameter': 'country',
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York',
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/metric?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "data": [
          {
            "value": "US",
            "count": 8420,
            "percentage": 54.63,
            "pageviews": 26891,
            "pageviews_percentage": 54.96,
            "bounce_rate": 41.2
          },
          {
            "value": "GB",
            "count": 2150,
            "percentage": 13.95,
            "pageviews": 6847,
            "pageviews_percentage": 13.99,
            "bounce_rate": 43.8
          }
        ],
        "totalCount": 87
      }
    }
    ```
  </div>
</div>


# Get Overview (/fr/docs/api/overview/overview)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/overview
    ```

    Returns high-level analytics metrics for a site.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  sessions: {
    description: 'Total number of sessions',
    type: 'number',
  },
  pageviews: {
    description: 'Total number of pageviews',
    type: 'number',
  },
  users: {
    description: 'Total unique users',
    type: 'number',
  },
  pages_per_session: {
    description: 'Average pages viewed per session',
    type: 'number',
  },
  bounce_rate: {
    description: 'Percentage of single-page sessions',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  session_duration: {
    description: 'Average session duration in seconds',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/overview',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "sessions": 15420,
        "pageviews": 48933,
        "users": 12847,
        "pages_per_session": 3.17,
        "bounce_rate": 42.8,
        "session_duration": 182.5
      }
    }
    ```
  </div>
</div>


# Get Page Titles (/fr/docs/api/overview/page-titles)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/page-titles
    ```

    Returns page-view metrics aggregated by HTML page title.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    <TypeTable
      type="{
  limit: {
    description: 'Maximum number of page titles to return',
    type: 'number',
    default: 10,
  },
  page: {
    description: 'Page number (1-indexed). When provided, the response is paginated and includes a total count',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  value: {
    description: 'The page title',
    type: 'string',
  },
  pathname: {
    description: 'A representative path for the title',
    type: 'string',
  },
  count: {
    description: 'Unique sessions that viewed the title',
    type: 'number',
  },
  percentage: {
    description: 'Share of total',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  pageviews: {
    description: 'Total pageviews',
    type: 'number',
  },
  bounce_rate: {
    description: 'Bounce rate percentage',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  time_on_page_seconds: {
    description: 'Average time on page in seconds',
    type: 'number',
  },
}"
    />

    When the `page` parameter is supplied, the response is paginated: `data` becomes an object `{ data: [...], totalCount: number }`.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/page-titles',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York',
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/page-titles?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "value": "Home | Acme",
          "pathname": "/",
          "count": 8200,
          "percentage": 41.2,
          "pageviews": 12400,
          "bounce_rate": 38.5,
          "time_on_page_seconds": 47.2
        }
      ]
    }
    ```
  </div>
</div>


# Get Overview (Time Series) (/fr/docs/api/overview/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/overview/time-series
    ```

    Returns time-series analytics data broken down by configurable time buckets. Useful for charting trends over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    required: false,
    default: 'hour',
  },
}"
    />

    #### Bucket Selection Guide [#bucket-selection-guide]

    | Bucket         | Best For                             |
    | -------------- | ------------------------------------ |
    | `minute`       | Real-time monitoring (last hour)     |
    | `five_minutes` | Short-term analysis (last few hours) |
    | `hour`         | Daily analysis                       |
    | `day`          | Weekly/monthly analysis              |
    | `week`         | Monthly/quarterly analysis           |
    | `month`        | Yearly analysis                      |

    ### Response [#response]

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'Datetime string, &#x22;YYYY-MM-DD HH:MM:SS&#x22;',
  },
  sessions: {
    description: 'Number of sessions in this bucket',
    type: 'number',
  },
  pageviews: {
    description: 'Number of pageviews in this bucket',
    type: 'number',
  },
  users: {
    description: 'Unique users in this bucket',
    type: 'number',
  },
  pages_per_session: {
    description: 'Average pages viewed per session',
    type: 'number',
  },
  bounce_rate: {
    description: 'Percentage of single-page sessions',
    type: 'number',
    typeDescription: 'Range: 0-100',
  },
  session_duration: {
    description: 'Average session duration in seconds',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/overview/time-series',
            params={
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/overview/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-01 00:00:00",
          "sessions": 1250,
          "pageviews": 3890,
          "users": 1100,
          "pages_per_session": 3.11,
          "bounce_rate": 41.5,
          "session_duration": 165.2
        },
        {
          "time": "2024-01-02 00:00:00",
          "sessions": 1420,
          "pageviews": 4520,
          "users": 1280,
          "pages_per_session": 3.18,
          "bounce_rate": 39.8,
          "session_duration": 178.4
        },
        {
          "time": "2024-01-03 00:00:00",
          "sessions": 1380,
          "pageviews": 4210,
          "users": 1190,
          "pages_per_session": 3.05,
          "bounce_rate": 42.1,
          "session_duration": 162.8
        }
      ]
    }
    ```
  </div>
</div>


# Get Performance by Dimension (/fr/docs/api/performance/by-dimension)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/performance/by-dimension
    ```

    Returns performance metrics broken down by a specific dimension (page, country, browser, etc.). Useful for identifying performance issues on specific pages or for specific user segments.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  dimension: {
    description: 'Dimension to break down by',
    type: 'string',
    typeDescription: '&#x22;pathname&#x22; | &#x22;country&#x22; | &#x22;device_type&#x22; | &#x22;browser&#x22; | &#x22;operating_system&#x22; | &#x22;region&#x22;',
    required: true,
  },
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    required: false,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  sort_by: {
    description: 'Field to sort by',
    type: 'string',
    default: 'event_count',
  },
  sort_order: {
    description: 'Sort direction',
    type: 'string',
    typeDescription: '&#x22;asc&#x22; | &#x22;desc&#x22;',
    default: 'desc',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Paginated response object',
    type: 'PaginatedResponse',
  },
}"
    />

    #### DimensionPerformance Object [#dimensionperformance-object]

    Each object includes the dimension value plus all percentiles:

    <TypeTable
      type="{
  pathname: {
    description: 'The dimension value (field name matches dimension param)',
    type: 'string',
  },
  event_count: {
    description: 'Number of performance events',
    type: 'number',
  },
  lcp_avg: {
    description: 'Average LCP',
    type: 'number',
  },
  lcp_p50: {
    description: 'LCP 50th percentile',
    type: 'number',
  },
  lcp_p75: {
    description: 'LCP 75th percentile',
    type: 'number',
  },
  lcp_p90: {
    description: 'LCP 90th percentile',
    type: 'number',
  },
  lcp_p99: {
    description: 'LCP 99th percentile',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/performance/by-dimension',
            params={
                'dimension': 'pathname',
                'sort_by': 'lcp_p75',
                'sort_order': 'desc',
                'limit': 10
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/by-dimension?dimension=pathname&sort_by=lcp_p75&sort_order=desc&limit=10");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "data": [
          {
            "pathname": "/dashboard",
            "event_count": 12450,
            "lcp_avg": 2850,
            "lcp_p50": 2400,
            "lcp_p75": 3200,
            "lcp_p90": 4100,
            "lcp_p99": 6500,
            "cls_avg": 0.08,
            "cls_p50": 0.05,
            "cls_p75": 0.12,
            "inp_avg": 180,
            "inp_p50": 150,
            "inp_p75": 220,
            "fcp_avg": 1450,
            "fcp_p50": 1300,
            "fcp_p75": 1700,
            "ttfb_avg": 520,
            "ttfb_p50": 480,
            "ttfb_p75": 680
          },
          {
            "pathname": "/reports",
            "event_count": 8920,
            "lcp_avg": 2650,
            "lcp_p50": 2200,
            "lcp_p75": 2900,
            "lcp_p90": 3800,
            "lcp_p99": 5800
          }
        ],
        "totalCount": 156
      }
    }
    ```
  </div>
</div>


# Get Performance Overview (/fr/docs/api/performance/overview)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/performance/overview
    ```

    Returns aggregate performance metrics with percentile breakdowns for all Core Web Vitals.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Performance metrics object',
    type: 'PerformanceMetrics',
  },
}"
    />

    #### PerformanceMetrics Object [#performancemetrics-object]

    Each metric (lcp, cls, inp, fcp, ttfb) includes the following percentiles:

    <TypeTable
      type="{
  lcp_p50: {
    description: 'LCP 50th percentile (median)',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  lcp_p75: {
    description: 'LCP 75th percentile',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  lcp_p90: {
    description: 'LCP 90th percentile',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  lcp_p99: {
    description: 'LCP 99th percentile',
    type: 'number',
    typeDescription: 'milliseconds',
  },
  total_performance_events: {
    description: 'Total number of performance measurements',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/performance/overview',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "lcp_p50": 1850,
        "lcp_p75": 2400,
        "lcp_p90": 3200,
        "lcp_p99": 5100,
        "cls_p50": 0.05,
        "cls_p75": 0.1,
        "cls_p90": 0.18,
        "cls_p99": 0.35,
        "inp_p50": 120,
        "inp_p75": 180,
        "inp_p90": 280,
        "inp_p99": 450,
        "fcp_p50": 1200,
        "fcp_p75": 1600,
        "fcp_p90": 2100,
        "fcp_p99": 3500,
        "ttfb_p50": 450,
        "ttfb_p75": 650,
        "ttfb_p90": 950,
        "ttfb_p99": 1800,
        "total_performance_events": 48521
      }
    }
    ```
  </div>
</div>


# Get Performance Time Series (/fr/docs/api/performance/time-series)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/performance/time-series
    ```

    Returns performance metrics over time, broken down by configurable time buckets. Useful for charting performance trends.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  bucket: {
    description: 'Time bucket size for grouping data. Defaults to &#x22;hour&#x22; when omitted.',
    type: 'TimeBucket',
    typeDescription: '&#x22;minute&#x22; | &#x22;five_minutes&#x22; | &#x22;ten_minutes&#x22; | &#x22;fifteen_minutes&#x22; | &#x22;hour&#x22; | &#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;',
    default: 'hour',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of time-bucketed performance data',
    type: 'PerformancePoint[]',
  },
}"
    />

    #### PerformancePoint Object [#performancepoint-object]

    Each point includes all percentiles for each metric plus:

    <TypeTable
      type="{
  time: {
    description: 'Start of the time bucket',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  event_count: {
    description: 'Number of performance events in this bucket',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/performance/time-series',
            params={
                'bucket': 'day',
                'start_date': '2024-01-01',
                'end_date': '2024-01-07',
                'time_zone': 'UTC'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/time-series?bucket=day&start_date=2024-01-01&end_date=2024-01-07&time_zone=UTC");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "time": "2024-01-01T00:00:00.000Z",
          "lcp_p50": 1820,
          "lcp_p75": 2350,
          "lcp_p90": 3100,
          "lcp_p99": 4900,
          "cls_p50": 0.04,
          "cls_p75": 0.09,
          "inp_p50": 115,
          "inp_p75": 175,
          "fcp_p50": 1180,
          "fcp_p75": 1580,
          "ttfb_p50": 440,
          "ttfb_p75": 640,
          "event_count": 6892
        },
        {
          "time": "2024-01-02T00:00:00.000Z",
          "lcp_p50": 1900,
          "lcp_p75": 2450,
          "lcp_p90": 3250,
          "lcp_p99": 5200,
          "cls_p50": 0.05,
          "cls_p75": 0.11,
          "inp_p50": 125,
          "inp_p75": 185,
          "fcp_p50": 1220,
          "fcp_p75": 1620,
          "ttfb_p50": 460,
          "ttfb_p75": 660,
          "event_count": 7234
        }
      ]
    }
    ```
  </div>
</div>


# Create Segment (/fr/docs/api/segments/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:site/segments
    ```

    Creates a saved segment. Members create site segments they own; admins and owners can also create organization-wide segments.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Segment name (1–80 characters)',
    type: 'string',
    required: true,
  },
  filters: {
    description: 'Filters that define the segment (1–20). Validated with the same schema as the `filters` parameter',
    type: 'Filter[]',
    typeDescription: 'See Filter Parameters in Getting Started',
    required: true,
  },
  description: {
    description: 'Optional notes (up to 500 characters)',
    type: 'string | null',
    required: false,
  },
  scope: {
    description: 'Where the segment is available. Organization-wide segments require an admin or owner',
    type: 'string',
    typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;',
    default: 'site',
    required: false,
  },
  isPublic: {
    description: 'Show on the public dashboard and private links',
    type: 'boolean',
    default: 'false',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created segment with status 201.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/1/segments" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"name": "Mobile organic from Germany", "filters": [{"parameter": "device_type", "type": "equals", "value": ["Mobile"]}, {"parameter": "channel", "type": "equals", "value": ["Organic Search"]}, {"parameter": "country", "type": "equals", "value": ["DE"]}]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({"name": "Mobile organic from Germany", "filters": [{"parameter": "device_type", "type": "equals", "value": ["Mobile"]}, {"parameter": "channel", "type": "equals", "value": ["Organic Search"]}, {"parameter": "country", "type": "equals", "value": ["DE"]}]})
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/1/segments',
            json={"name": "Mobile organic from Germany", "filters": [{"parameter": "device_type", "type": "equals", "value": ["Mobile"]}, {"parameter": "channel", "type": "equals", "value": ["Organic Search"]}, {"parameter": "country", "type": "equals", "value": ["DE"]}]},
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "segmentId": 12,
      "siteId": 1,
      "organizationId": "org_abc123",
      "userId": "user_xyz",
      "name": "Mobile organic from Germany",
      "description": null,
      "filters": [
        { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
        { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
        { "parameter": "country", "type": "equals", "value": ["DE"] }
      ],
      "isPublic": false,
      "type": "segment",
      "canEdit": true,
      "createdAt": "2026-09-02T10:15:00.000Z",
      "updatedAt": "2026-09-02T10:15:00.000Z"
    }
    ```
  </div>
</div>


# Delete Segment (/fr/docs/api/segments/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/segments/:segmentId
    ```

    Deletes a saved segment. Admins and owners can delete any segment; members can delete segments they created. Links that already expanded the segment's filters keep working.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  segmentId: {
    description: 'Segment ID',
    type: 'number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the segment was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/1/segments/12" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments/12',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/1/segments/12',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Segment (/fr/docs/api/segments/get)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/segments/:segmentId
    ```

    Returns one saved segment.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  segmentId: {
    description: 'Segment ID',
    type: 'number',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns the segment.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/segments/12" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments/12',
          {
            method: 'GET',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/segments/12',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "segmentId": 12,
      "siteId": 1,
      "organizationId": "org_abc123",
      "userId": "user_xyz",
      "name": "Mobile organic from Germany",
      "description": null,
      "filters": [
        { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
        { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
        { "parameter": "country", "type": "equals", "value": ["DE"] }
      ],
      "isPublic": false,
      "type": "segment",
      "canEdit": true,
      "createdAt": "2026-09-02T10:15:00.000Z",
      "updatedAt": "2026-09-02T10:15:00.000Z"
    }
    ```
  </div>
</div>


# Get Segments (/fr/docs/api/segments/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/segments
    ```

    Returns the saved segments available on a site: its own plus organization-wide ones. Callers without site access only see segments shown on the public dashboard.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    Returns an array of segments, sorted by name.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/segments" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments',
          {
            method: 'GET',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/segments',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    [
      {
        "segmentId": 12,
        "siteId": 1,
        "organizationId": "org_abc123",
        "userId": "user_xyz",
        "name": "Mobile organic from Germany",
        "description": null,
        "filters": [
          { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
          { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
          { "parameter": "country", "type": "equals", "value": ["DE"] }
        ],
        "isPublic": false,
        "type": "segment",
        "canEdit": true,
        "createdAt": "2026-09-02T10:15:00.000Z",
        "updatedAt": "2026-09-02T10:15:00.000Z"
      }
    ]
    ```
  </div>
</div>


# Update Segment (/fr/docs/api/segments/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:site/segments/:segmentId
    ```

    Updates a saved segment. Admins and owners can edit any segment; members can edit segments they created. Only the fields you send change.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  segmentId: {
    description: 'Segment ID',
    type: 'number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Segment name (1–80 characters)',
    type: 'string',
    required: false,
  },
  filters: {
    description: 'Filters that define the segment (1–20). Validated with the same schema as the `filters` parameter',
    type: 'Filter[]',
    typeDescription: 'See Filter Parameters in Getting Started',
    required: false,
  },
  description: {
    description: 'Optional notes (up to 500 characters)',
    type: 'string | null',
    required: false,
  },
  scope: {
    description: 'Where the segment is available. Organization-wide segments require an admin or owner',
    type: 'string',
    typeDescription: '&#x22;site&#x22; | &#x22;organization&#x22;',
    default: 'site',
    required: false,
  },
  isPublic: {
    description: 'Show on the public dashboard and private links',
    type: 'boolean',
    default: 'false',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the updated segment.

    <TypeTable
      type="{
  segmentId: { description: 'Segment ID', type: 'number' },
  siteId: { description: 'Site ID, or null for an organization-wide segment', type: 'number | null' },
  organizationId: { description: 'Owning organization', type: 'string' },
  userId: { description: 'Creator, or null once that account is deleted', type: 'string | null' },
  name: { description: 'Segment name', type: 'string' },
  description: { description: 'Notes', type: 'string | null' },
  filters: { description: 'The filters that define the segment', type: 'Filter[]' },
  isPublic: { description: 'Shown on the public dashboard and private links', type: 'boolean' },
  type: { description: 'Always &#x22;segment&#x22; today; reserved for cohorts', type: 'string' },
  canEdit: { description: 'Whether the caller may edit or delete this segment', type: 'boolean' },
  createdAt: { description: 'ISO 8601 timestamp', type: 'string' },
  updatedAt: { description: 'ISO 8601 timestamp', type: 'string' },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/sites/1/segments/12" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"name": "Mobile organic (DE)", "isPublic": true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/segments/12',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({"name": "Mobile organic (DE)", "isPublic": true})
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/sites/1/segments/12',
            json={"name": "Mobile organic (DE)", "isPublic": true},
            headers={'Authorization': 'Bearer your_api_key_here'}
        )

        data = response.json()
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "segmentId": 12,
      "siteId": 1,
      "organizationId": "org_abc123",
      "userId": "user_xyz",
      "name": "Mobile organic (DE)",
      "description": null,
      "filters": [
        { "parameter": "device_type", "type": "equals", "value": ["Mobile"] },
        { "parameter": "channel", "type": "equals", "value": ["Organic Search"] },
        { "parameter": "country", "type": "equals", "value": ["DE"] }
      ],
      "isPublic": true,
      "type": "segment",
      "canEdit": true,
      "createdAt": "2026-09-02T10:15:00.000Z",
      "updatedAt": "2026-09-02T10:15:00.000Z"
    }
    ```
  </div>
</div>


# Delete Session Replay (/fr/docs/api/session-replay/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:site/session-replay/:sessionId
    ```

    Permanently deletes a session replay recording. Requires site write access.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  sessionId: {
    description: 'The session to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the deletion was successful',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
        req = Net::HTTP::Delete.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Session Replay Events (/fr/docs/api/session-replay/events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/session-replay/:sessionId
    ```

    Returns the rrweb events and metadata needed to reconstruct a session replay.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
  sessionId: {
    description: 'The session to fetch',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  events: {
    description: 'Array of rrweb event objects, replayed in order to reconstruct the session. Each carries a timestamp and rrweb-format payload.',
    type: 'RRWebEvent[]',
  },
  metadata: {
    description: &#x22;The session replay metadata object (same fields as a list item, enriched with the user's traits)&#x22;,
    type: 'SessionReplayMetadata',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/session-replay/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "events": [
        {
          "type": 4,
          "timestamp": 1705320000000,
          "data": { }
        }
      ],
      "metadata": {
        "session_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "duration_ms": 48200,
        "event_count": 312,
        "browser": "Chrome",
        "...": "..."
      }
    }
    ```
  </div>
</div>


# Get Session Replays (/fr/docs/api/session-replay/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/session-replay/list
    ```

    Returns recorded session replays with metadata, newest first.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters) plus the following:

    <TypeTable
      type="{
  limit: {
    description: 'Number of results to return',
    type: 'number',
    default: 50,
  },
  offset: {
    description: 'Number of results to skip',
    type: 'number',
    default: 0,
  },
  userId: {
    description: 'Restrict to a single user',
    type: 'string',
    required: false,
  },
  minDuration: {
    description: 'Minimum replay duration in seconds',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session replay objects',
    type: 'SessionReplay[]',
  },
}"
    />

    #### SessionReplay Object [#sessionreplay-object]

    Identified users are enriched with their `traits`.

    <TypeTable
      type="{
  session_id: {
    description: 'Unique session identifier',
    type: 'string',
  },
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  start_time: {
    description: 'Replay start time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  end_time: {
    description: 'Replay end time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  duration_ms: {
    description: 'Duration in milliseconds',
    type: 'number',
  },
  page_url: {
    description: 'Entry page',
    type: 'string',
  },
  event_count: {
    description: 'Number of recorded events',
    type: 'number',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/session-replay/list',
            params={
                'limit': 50,
                'offset': 0,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/session-replay/list?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
          "user_id": "dev_xyz789",
          "identified_user_id": "user@example.com",
          "start_time": "2024-01-31T14:00:00.000Z",
          "end_time": "2024-01-31T14:00:48.200Z",
          "duration_ms": 48200,
          "page_url": "/",
          "event_count": 312,
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "browser": "Chrome",
          "browser_version": "120.0.0",
          "operating_system": "macOS",
          "operating_system_version": "14.2",
          "device_type": "desktop",
          "screen_width": 1920,
          "screen_height": 1080
        }
      ]
    }
    ```
  </div>
</div>


# Get Session (/fr/docs/api/sessions/get)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/sessions/:sessionId
    ```

    Returns detailed information about a specific session including all events and pageviews.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  sessionId: {
    description: 'Session ID',
    type: 'string',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  limit: {
    description: 'Number of events to return',
    type: 'number',
    default: 100,
  },
  offset: {
    description: 'Number of events to skip',
    type: 'number',
    default: 0,
  },
  minutes: {
    description: 'Only return events from the last N minutes',
    type: 'number',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Session details object',
    type: 'SessionDetails',
  },
}"
    />

    #### SessionDetails Object [#sessiondetails-object]

    <TypeTable
      type="{
  session: {
    description: 'Session metadata',
    type: 'SessionMeta',
  },
  events: {
    description: 'Array of events in the session',
    type: 'Event[]',
  },
  pagination: {
    description: 'Pagination info for events',
    type: 'Pagination',
  },
}"
    />

    #### Event Object [#event-object]

    <TypeTable
      type="{
  timestamp: {
    description: 'Event timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
  },
  hostname: {
    description: 'Hostname',
    type: 'string',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;error&#x22; | &#x22;outbound&#x22; | &#x22;button_click&#x22; | &#x22;copy&#x22; | &#x22;form_submit&#x22; | &#x22;input_change&#x22;',
  },
  event_name: {
    description: 'Custom event name (for custom_event type)',
    type: 'string',
  },
  props: {
    description: 'Event properties',
    type: 'object',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/sessions/sess_abc123',
            params={'limit': 50},
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/sessions/sess_abc123?limit=50");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "session": {
          "session_id": "sess_abc123",
          "user_id": "dev_xyz789",
          "country": "US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:04:05.000Z",
          "session_duration": 245,
          "pageviews": 5,
          "events": 7,
          "entry_page": "/",
          "exit_page": "/pricing"
        },
        "events": [
          {
            "timestamp": "2024-01-31T14:00:00.000Z",
            "pathname": "/",
            "hostname": "example.com",
            "page_title": "Home",
            "type": "pageview",
            "referrer": "https://google.com"
          },
          {
            "timestamp": "2024-01-31T14:01:30.000Z",
            "pathname": "/",
            "hostname": "example.com",
            "type": "custom_event",
            "event_name": "cta_click",
            "props": { "button": "hero" }
          }
        ],
        "pagination": {
          "total": 7,
          "limit": 50,
          "offset": 0,
          "hasMore": false
        }
      }
    }
    ```
  </div>
</div>


# Get Sessions (/fr/docs/api/sessions/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/sessions
    ```

    Returns a paginated list of sessions with their analytics data.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  limit: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  user_id: {
    description: 'Filter sessions by user ID',
    type: 'string',
    required: false,
  },
  identified_only: {
    description: 'Only return sessions from identified users',
    type: 'string',
    typeDescription: '&#x22;true&#x22; | &#x22;false&#x22;',
    default: 'false',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of session objects',
    type: 'Session[]',
  },
}"
    />

    #### Session Object [#session-object]

    <TypeTable
      type="{
  session_id: {
    description: 'Unique session identifier',
    type: 'string',
  },
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  traits: {
    description: 'Custom user traits',
    type: 'object | null',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
  },
  channel: {
    description: 'Traffic channel',
    type: 'string',
  },
  entry_page: {
    description: 'First page visited',
    type: 'string',
  },
  exit_page: {
    description: 'Last page visited',
    type: 'string',
  },
  pageviews: {
    description: 'Number of pageviews',
    type: 'number',
  },
  events: {
    description: 'Number of custom events',
    type: 'number',
  },
  session_duration: {
    description: 'Duration in seconds',
    type: 'number',
  },
  session_start: {
    description: 'Session start time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  session_end: {
    description: 'Session end time',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  utm_source: {
    description: 'UTM source parameter',
    type: 'string',
  },
  utm_medium: {
    description: 'UTM medium parameter',
    type: 'string',
  },
  utm_campaign: {
    description: 'UTM campaign parameter',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/sessions',
            params={
                'page': 1,
                'limit': 20,
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/sessions?page=1&limit=20&start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "session_id": "sess_abc123",
          "user_id": "dev_xyz789",
          "identified_user_id": "user@example.com",
          "traits": { "plan": "pro" },
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "referrer": "https://google.com",
          "channel": "organic",
          "entry_page": "/",
          "exit_page": "/pricing",
          "pageviews": 5,
          "events": 2,
          "session_duration": 245,
          "session_start": "2024-01-31T14:00:00.000Z",
          "session_end": "2024-01-31T14:04:05.000Z",
          "utm_source": "google",
          "utm_medium": "cpc",
          "utm_campaign": "brand"
        }
      ]
    }
    ```
  </div>
</div>


# Get Session Locations (/fr/docs/api/sessions/locations)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/sessions/locations
    ```

    Returns aggregated session locations with coordinates for map visualization.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of location objects',
    type: 'Location[]',
  },
}"
    />

    #### Location Object [#location-object]

    <TypeTable
      type="{
  lat: {
    description: 'Latitude coordinate',
    type: 'number',
  },
  lon: {
    description: 'Longitude coordinate',
    type: 'number',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  count: {
    description: 'Number of sessions from this location',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/sessions/locations',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/sessions/locations?start_date=2024-01-01&end_date=2024-01-31");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "lat": 37.7749,
          "lon": -122.4194,
          "city": "San Francisco",
          "country": "US",
          "count": 1250
        },
        {
          "lat": 40.7128,
          "lon": -74.006,
          "city": "New York",
          "country": "US",
          "count": 980
        },
        {
          "lat": 51.5074,
          "lon": -0.1278,
          "city": "London",
          "country": "GB",
          "count": 650
        }
      ]
    }
    ```
  </div>
</div>


# Create Team (/fr/docs/api/teams/create)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/organizations/:organizationId/teams
    ```

    Creates a team in an organization. Requires admin/owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Team name',
    type: 'string',
    required: true,
  },
  memberUserIds: {
    description: 'User IDs to add to the team (must be members of the organization)',
    type: 'string[]',
    required: false,
  },
  siteIds: {
    description: 'Site IDs the team can access (must belong to the organization)',
    type: 'number[]',
    required: false,
  },
}"
    />

    ### Response [#response]

    Returns the created team with HTTP 201.

    <TypeTable
      type="{
  id: {
    description: 'Team ID',
    type: 'string',
  },
  name: {
    description: 'Team name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID the team belongs to',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when the team was created',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Timestamp when the team was last updated',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  members: {
    description: 'Array of added user IDs',
    type: 'string[]',
  },
  siteIds: {
    description: 'Array of granted site IDs',
    type: 'number[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/organizations/org_abc123/teams" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"name": "Marketing", "memberUserIds": ["user_123"], "siteIds": [123]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/teams`,
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Marketing',
              memberUserIds: ['user_123'],
              siteIds: [123]
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.post(
            f'https://app.rybbit.io/api/organizations/{organization_id}/teams',
            json={
                'name': 'Marketing',
                'memberUserIds': ['user_123'],
                'siteIds': [123]
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/teams");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'name' => 'Marketing',
            'memberUserIds' => ['user_123'],
            'siteIds' => [123]
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/teams")
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = {
          name: 'Marketing',
          memberUserIds: ['user_123'],
          siteIds: [123]
        }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        body := bytes.NewBuffer([]byte(`{
          "name": "Marketing",
          "memberUserIds": ["user_123"],
          "siteIds": [123]
        }`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/organizations/"+organizationId+"/teams", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .post(format!("https://app.rybbit.io/api/organizations/{}/teams", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "name": "Marketing",
                "memberUserIds": ["user_123"],
                "siteIds": [123]
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"name\": \"Marketing\", \"memberUserIds\": [\"user_123\"], \"siteIds\": [123]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/teams"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"name\": \"Marketing\", \"memberUserIds\": [\"user_123\"], \"siteIds\": [123]}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync($"https://app.rybbit.io/api/organizations/{organizationId}/teams", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "team_xyz789",
      "name": "Marketing",
      "organizationId": "org_abc123",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "members": ["user_123"],
      "siteIds": [123]
    }
    ```
  </div>
</div>


# Delete Team (/fr/docs/api/teams/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/organizations/:organizationId/teams/:teamId
    ```

    Deletes a team. Requires admin/owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
  teamId: {
    description: 'ID of the team to delete',
    type: 'string',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the team was deleted',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789')
        request = Net::HTTP::Delete.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Teams (/fr/docs/api/teams/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/organizations/:organizationId/teams
    ```

    Returns the teams in an organization, with their members and accessible sites.

    Any organization member may call this. Members who are not an admin/owner only see the teams they belong to.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  teams: {
    description: 'Array of teams in the organization',
    type: 'array',
  },
}"
    />

    #### Team Object [#team-object]

    Each team in the `teams` array contains:

    <TypeTable
      type="{
  id: {
    description: 'Team ID',
    type: 'string',
  },
  name: {
    description: 'Team name',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID the team belongs to',
    type: 'string',
  },
  createdAt: {
    description: 'Timestamp when the team was created',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Timestamp when the team was last updated',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  members: {
    description: 'Members of the team',
    type: 'array',
  },
  sites: {
    description: 'Sites the team can access',
    type: 'array',
  },
}"
    />

    #### Member Object [#member-object]

    <TypeTable
      type="{
  userId: {
    description: 'User ID',
    type: 'string',
  },
  userName: {
    description: 'User display name',
    type: 'string',
  },
  userEmail: {
    description: 'User email address',
    type: 'string',
  },
}"
    />

    #### Site Object [#site-object]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'number',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/organizations/org_abc123/teams" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const organizationId = 'org_abc123';
        const response = await fetch(
          `https://app.rybbit.io/api/organizations/${organizationId}/teams`,
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        organization_id = 'org_abc123'
        response = requests.get(
            f'https://app.rybbit.io/api/organizations/{organization_id}/teams',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $organizationId = 'org_abc123';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://app.rybbit.io/api/organizations/{$organizationId}/teams");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        organization_id = 'org_abc123'
        uri = URI("https://app.rybbit.io/api/organizations/#{organization_id}/teams")
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        organizationId := "org_abc123"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/organizations/"+organizationId+"/teams", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let organization_id = "org_abc123";
        let client = reqwest::Client::new();
        let res = client
            .get(format!("https://app.rybbit.io/api/organizations/{}/teams", organization_id))
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String organizationId = "org_abc123";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/" + organizationId + "/teams"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var organizationId = "org_abc123";
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync($"https://app.rybbit.io/api/organizations/{organizationId}/teams");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "teams": [
        {
          "id": "team_xyz789",
          "name": "Marketing",
          "organizationId": "org_abc123",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "updatedAt": "2024-02-20T14:15:00.000Z",
          "members": [
            {
              "userId": "user_123",
              "userName": "John Doe",
              "userEmail": "john@example.com"
            }
          ],
          "sites": [
            {
              "siteId": 123,
              "domain": "example.com",
              "name": "Example Site"
            }
          ]
        }
      ]
    }
    ```
  </div>
</div>


# Update Team (/fr/docs/api/teams/update)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/organizations/:organizationId/teams/:teamId
    ```

    Updates a team's name, members, or site access. Requires admin/owner role.

    When `memberUserIds` or `siteIds` is provided, it **replaces** the team's entire existing set (it is not merged). Omit a field to leave it unchanged.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  organizationId: {
    description: 'Organization ID',
    type: 'string',
    required: true,
  },
  teamId: {
    description: 'ID of the team to update',
    type: 'string',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  name: {
    description: 'Updated team name',
    type: 'string',
    required: false,
  },
  memberUserIds: {
    description: 'User IDs to set as the team members (replaces the existing set)',
    type: 'string[]',
    required: false,
  },
  siteIds: {
    description: 'Site IDs to set as the team site access (replaces the existing set)',
    type: 'number[]',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the team was updated',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Growth",
            "memberUserIds": ["user_123", "user_456"]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              name: 'Growth',
              memberUserIds: ['user_123', 'user_456']
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789',
            json={
                'name': 'Growth',
                'memberUserIds': ['user_123', 'user_456']
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'name' => 'Growth',
            'memberUserIds' => ['user_123', 'user_456']
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789')
        request = Net::HTTP::Put.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          name: 'Growth',
          memberUserIds: ['user_123', 'user_456']
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "name": "Growth",
            "memberUserIds": []string{"user_123", "user_456"},
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("PUT", "https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "name": "Growth",
            "memberUserIds": ["user_123", "user_456"]
        });

        let client = reqwest::Client::new();
        let res = client
            .put("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "name": "Growth",
          "memberUserIds": ["user_123", "user_456"]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            name = "Growth",
            memberUserIds = new[] { "user_123", "user_456" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PutAsync("https://app.rybbit.io/api/organizations/org_abc123/teams/team_xyz789", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Delete Site (/fr/docs/api/sites/delete)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    DELETE /api/sites/:siteId
    ```

    Permanently deletes a site and all its associated data. This action cannot be undone. Requires admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the deletion was successful',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X DELETE "https://app.rybbit.io/api/sites/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123',
          {
            method: 'DELETE',
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.delete(
            'https://app.rybbit.io/api/sites/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123')
        req = Net::HTTP::Delete.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("DELETE", "https://app.rybbit.io/api/sites/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .delete("https://app.rybbit.io/api/sites/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .DELETE()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.DeleteAsync("https://app.rybbit.io/api/sites/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true
    }
    ```
  </div>
</div>


# Get Excluded Countries (/fr/docs/api/sites/excluded-countries)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId/excluded-countries
    ```

    Returns the list of country codes that are excluded from tracking.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedCountries: {
    description: 'Array of excluded country codes (2-letter ISO codes)',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-countries" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-countries',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-countries',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-countries');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-countries')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-countries", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-countries")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-countries"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-countries");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedCountries": [
        "CN",
        "RU",
        "KP"
      ]
    }
    ```
  </div>
</div>


# Get Excluded Hostnames (/fr/docs/api/sites/excluded-hostnames)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/excluded-hostnames
    ```

    Returns the list of hostnames excluded from analytics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedHostnames: {
    description: 'Array of excluded hostnames',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-hostnames" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-hostnames',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-hostnames',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-hostnames');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-hostnames')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-hostnames", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-hostnames")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-hostnames"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-hostnames");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedHostnames": [
        "staging.example.com"
      ]
    }
    ```
  </div>
</div>


# Get Excluded IPs (/fr/docs/api/sites/excluded-ips)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId/excluded-ips
    ```

    Returns the list of IP addresses and CIDR ranges that are excluded from tracking.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedIPs: {
    description: 'Array of excluded IP addresses or CIDR ranges',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-ips" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-ips',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-ips',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-ips');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-ips')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-ips", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-ips")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-ips"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-ips");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedIPs": [
        "192.168.1.1",
        "10.0.0.0/8",
        "172.16.0.0/12"
      ]
    }
    ```
  </div>
</div>


# Get Excluded Paths (/fr/docs/api/sites/excluded-paths)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/excluded-paths
    ```

    Returns the list of URL paths excluded from analytics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedPaths: {
    description: 'Array of excluded URL paths',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-paths" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-paths',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-paths',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-paths');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-paths')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-paths", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-paths")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-paths"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-paths");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedPaths": [
        "/admin",
        "/internal/*"
      ]
    }
    ```
  </div>
</div>


# Get Excluded User Agents (/fr/docs/api/sites/excluded-user-agents)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/excluded-user-agents
    ```

    Returns the list of user-agent patterns excluded from analytics.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  excludedUserAgents: {
    description: 'Array of excluded user-agent patterns',
    type: 'string[]',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/excluded-user-agents" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/excluded-user-agents',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/excluded-user-agents',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/excluded-user-agents');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/excluded-user-agents')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/excluded-user-agents", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/excluded-user-agents")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/excluded-user-agents"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/excluded-user-agents");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "excludedUserAgents": [
        "*HeadlessChrome*"
      ]
    }
    ```
  </div>
</div>


# Export PDF Report (/fr/docs/api/sites/export-pdf)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/export/pdf
    ```

    Generates a downloadable PDF analytics report for a date range.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  start_date: {
    description: 'Start of the date range',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
    required: true,
  },
  end_date: {
    description: 'End of the date range',
    type: 'string',
    typeDescription: 'YYYY-MM-DD',
    required: true,
  },
  time_zone: {
    description: 'IANA timezone',
    type: 'string',
    required: true,
  },
  filters: {
    description: 'JSON-encoded filter array (same format as the Common Parameters filters)',
    type: 'string',
  },
}"
    />

    ### Response [#response]

    Returns a binary PDF file (`Content-Type: application/pdf`). Save the response body to a `.pdf` file rather than parsing it as JSON.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here" \
          -o report.pdf
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const blob = await response.blob();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/export/pdf',
            params={
                'start_date': '2024-01-01',
                'end_date': '2024-01-31',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        with open('report.pdf', 'wb') as f:
            f.write(response.content)
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        file_put_contents('report.pdf', $response);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'

        uri = URI('https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        File.binwrite('report.pdf', res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        out, _ := os.Create("report.pdf")
        defer out.Close()
        io.Copy(out, resp.Body)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let bytes = res.bytes().await?;
        std::fs::write("report.pdf", &bytes)?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<Path> response = client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("report.pdf")));
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/export/pdf?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
        var bytes = await response.Content.ReadAsByteArrayAsync();
        File.WriteAllBytes("report.pdf", bytes);
        ```
      </Tab>
    </Tabs>
  </div>
</div>


# Get Private Link Config (/fr/docs/api/sites/get-private-link)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId/private-link-config
    ```

    Returns the private link key configuration. Private links allow sharing analytics with a secret key without requiring authentication.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  data: {
    description: 'Private link configuration',
    type: 'object',
  },
}"
    />

    #### Data Object [#data-object]

    <TypeTable
      type="{
  privateLinkKey: {
    description: 'Private link key, or null if not generated',
    type: 'string | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/private-link-config" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/private-link-config',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/private-link-config',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/private-link-config');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/private-link-config')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/private-link-config", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/private-link-config")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/private-link-config"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/private-link-config");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": {
        "privateLinkKey": "a1b2c3d4e5f6"
      }
    }
    ```
  </div>
</div>


# Get Site (/fr/docs/api/sites/get)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:siteId
    ```

    Returns detailed information about a specific site including its configuration.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  id: {
    description: 'Site UUID',
    type: 'string | null',
  },
  siteId: {
    description: 'Numeric site ID',
    type: 'number',
  },
  name: {
    description: 'Site name',
    type: 'string',
  },
  domain: {
    description: 'Site domain',
    type: 'string',
  },
  createdAt: {
    description: 'Creation timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  updatedAt: {
    description: 'Last update timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  createdBy: {
    description: 'User ID who created the site',
    type: 'string',
  },
  organizationId: {
    description: 'Organization ID',
    type: 'string | null',
  },
  public: {
    description: 'Whether the site analytics are publicly accessible',
    type: 'boolean',
  },
  saltUserIds: {
    description: 'Whether user IDs are salted for privacy',
    type: 'boolean',
  },
  blockBots: {
    description: 'Whether bot traffic is blocked',
    type: 'boolean',
  },
  isOwner: {
    description: 'Whether the current user owns this site',
    type: 'boolean',
  },
  sessionReplay: {
    description: 'Whether session replay is enabled',
    type: 'boolean',
  },
  webVitals: {
    description: 'Whether Web Vitals tracking is enabled',
    type: 'boolean',
  },
  trackErrors: {
    description: 'Whether error tracking is enabled',
    type: 'boolean',
  },
  trackOutbound: {
    description: 'Whether outbound link tracking is enabled',
    type: 'boolean',
  },
  trackUrlParams: {
    description: 'Whether URL parameter tracking is enabled',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "id": "site_abc123",
      "siteId": 123,
      "name": "My Website",
      "domain": "example.com",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-31T14:00:00.000Z",
      "createdBy": "user_xyz789",
      "organizationId": "org_def456",
      "public": false,
      "saltUserIds": false,
      "blockBots": true,
      "isOwner": true,
      "sessionReplay": true,
      "webVitals": true,
      "trackErrors": true,
      "trackOutbound": true,
      "trackUrlParams": false
    }
    ```
  </div>
</div>


# Get Site Has Data (/fr/docs/api/sites/has-data)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/has-data
    ```

    Returns whether the site has received any analytics events.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  hasData: {
    description: 'Whether the site has received any analytics events',
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/has-data" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/has-data',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/has-data',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/has-data');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/has-data')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/has-data", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/has-data")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/has-data"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/has-data");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "hasData": true
    }
    ```
  </div>
</div>


# Get Site Public Status (/fr/docs/api/sites/is-public)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/is-public
    ```

    Returns whether the site's analytics are publicly accessible.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  isPublic: {
    description: &#x22;Whether the site's analytics are publicly accessible&#x22;,
    type: 'boolean',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/is-public" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/is-public',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/is-public',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/is-public');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/is-public')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/is-public", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/is-public")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/is-public"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/is-public");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "isPublic": false
    }
    ```
  </div>
</div>


# Update Site Config (/fr/docs/api/sites/update-config)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    PUT /api/sites/:siteId/config
    ```

    Updates site configuration settings. All fields are optional - only include the fields you want to update. Requires admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  domain: {
    description: 'Site domain',
    type: 'string',
    typeDescription: 'Valid domain format (e.g., example.com)',
    required: false,
  },
  public: {
    description: 'Make analytics publicly accessible',
    type: 'boolean',
    required: false,
  },
  saltUserIds: {
    description: 'Salt user IDs for privacy',
    type: 'boolean',
    required: false,
  },
  blockBots: {
    description: 'Block bot traffic',
    type: 'boolean',
    required: false,
  },
  excludedIPs: {
    description: 'List of IP addresses or CIDR ranges to exclude',
    type: 'string[]',
    typeDescription: 'Max 100 entries',
    required: false,
  },
  excludedCountries: {
    description: 'List of country codes to exclude',
    type: 'string[]',
    typeDescription: '2-letter ISO codes (e.g., US, GB)',
    required: false,
  },
  sessionReplay: {
    description: 'Enable session replay',
    type: 'boolean',
    required: false,
  },
  webVitals: {
    description: 'Enable Web Vitals tracking',
    type: 'boolean',
    required: false,
  },
  trackErrors: {
    description: 'Enable error tracking',
    type: 'boolean',
    required: false,
  },
  trackOutbound: {
    description: 'Enable outbound link tracking',
    type: 'boolean',
    required: false,
  },
  trackUrlParams: {
    description: 'Enable URL parameter tracking',
    type: 'boolean',
    required: false,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the update was successful',
    type: 'boolean',
  },
  message: {
    description: 'Status message',
    type: 'string',
  },
  config: {
    description: 'Updated site configuration',
    type: 'object',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X PUT "https://app.rybbit.io/api/sites/123/config" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"public": true, "blockBots": true, "excludedCountries": ["CN", "RU"]}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/config',
          {
            method: 'PUT',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              public: true,
              blockBots: true,
              excludedCountries: ['CN', 'RU']
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.put(
            'https://app.rybbit.io/api/sites/123/config',
            json={
                'public': True,
                'blockBots': True,
                'excludedCountries': ['CN', 'RU']
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/config');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'public' => true,
            'blockBots' => true,
            'excludedCountries' => ['CN', 'RU']
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/config')
        req = Net::HTTP::Put.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = { public: true, blockBots: true, excludedCountries: ['CN', 'RU'] }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{"public": true, "blockBots": true, "excludedCountries": ["CN", "RU"]}`))
        req, _ := http.NewRequest("PUT", "https://app.rybbit.io/api/sites/123/config", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .put("https://app.rybbit.io/api/sites/123/config")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "public": true,
                "blockBots": true,
                "excludedCountries": ["CN", "RU"]
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"public\": true, \"blockBots\": true, \"excludedCountries\": [\"CN\", \"RU\"]}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/config"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"public\": true, \"blockBots\": true, \"excludedCountries\": [\"CN\", \"RU\"]}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PutAsync("https://app.rybbit.io/api/sites/123/config", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "message": "Site configuration updated successfully",
      "config": {
        "public": true,
        "saltUserIds": false,
        "blockBots": true,
        "excludedIPs": [],
        "excludedCountries": ["CN", "RU"],
        "sessionReplay": true,
        "webVitals": true,
        "trackErrors": true,
        "trackOutbound": true,
        "trackUrlParams": false
      }
    }
    ```
  </div>
</div>


# Update Private Link Config (/fr/docs/api/sites/update-private-link)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/sites/:siteId/private-link-config
    ```

    Generates or revokes a private link key for sharing analytics without authentication. Requires admin or owner role.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  siteId: {
    description: 'Site ID',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Request Body [#request-body]

    <TypeTable
      type="{
  action: {
    description: 'Action to perform',
    type: 'string',
    typeDescription: '&#x22;generate_private_link_key&#x22; | &#x22;revoke_private_link_key&#x22;',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the request was successful',
    type: 'boolean',
  },
  data: {
    description: 'Updated private link configuration',
    type: 'object',
  },
}"
    />

    #### Data Object [#data-object]

    <TypeTable
      type="{
  privateLinkKey: {
    description: 'New private link key (for generate), or null (for revoke)',
    type: 'string | null',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/sites/123/private-link-config" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{"action": "generate_private_link_key"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/private-link-config',
          {
            method: 'POST',
            headers: {
              'Authorization': 'Bearer your_api_key_here',
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              action: 'generate_private_link_key'
            })
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.post(
            'https://app.rybbit.io/api/sites/123/private-link-config',
            json={
                'action': 'generate_private_link_key'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/private-link-config');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'action' => 'generate_private_link_key'
        ]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/private-link-config')
        req = Net::HTTP::Post.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'
        req['Content-Type'] = 'application/json'
        req.body = { action: 'generate_private_link_key' }.to_json

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := bytes.NewBuffer([]byte(`{"action": "generate_private_link_key"}`))
        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/sites/123/private-link-config", body)
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/sites/123/private-link-config")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&serde_json::json!({
                "action": "generate_private_link_key"
            }))
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        String json = "{\"action\": \"generate_private_link_key\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/private-link-config"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            "{\"action\": \"generate_private_link_key\"}",
            Encoding.UTF8,
            "application/json"
        );

        var response = await client.PostAsync("https://app.rybbit.io/api/sites/123/private-link-config", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "success": true,
      "data": {
        "privateLinkKey": "f6e5d4c3b2a1"
      }
    }
    ```
  </div>
</div>


# Get User Trait Keys (/fr/docs/api/user-traits/keys)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/user-traits/keys
    ```

    Returns the known user trait keys with the number of users that have each.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    This endpoint takes no query parameters.

    ### Response [#response]

    <TypeTable
      type="{
  keys: {
    description: 'Array of user trait keys',
    type: 'TraitKey[]',
  },
}"
    />

    #### TraitKey Object [#traitkey-object]

    <TypeTable
      type="{
  key: {
    description: 'The trait name',
    type: 'string',
  },
  userCount: {
    description: 'Number of users that have this trait',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/user-traits/keys" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/user-traits/keys',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/user-traits/keys',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/user-traits/keys');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/user-traits/keys')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/user-traits/keys", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/user-traits/keys")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/user-traits/keys"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/user-traits/keys");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "keys": [
        { "key": "plan", "userCount": 1240 },
        { "key": "company", "userCount": 860 }
      ]
    }
    ```
  </div>
</div>


# Get Users by Trait (/fr/docs/api/user-traits/users)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/user-traits/users
    ```

    Returns users matching a specific trait key and value, with location and session metadata.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  key: {
    description: 'The trait key to match on',
    type: 'string',
    required: true,
  },
  value: {
    description: 'The trait value to match on',
    type: 'string',
    required: true,
  },
  limit: {
    description: 'Maximum number of users to return',
    type: 'number',
    default: '50',
  },
  offset: {
    description: 'Number of users to skip',
    type: 'number',
    default: '0',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  users: {
    description: 'Array of matching users',
    type: 'TraitUser[]',
  },
  total: {
    description: 'Total number of matching users',
    type: 'number',
  },
  hasMore: {
    description: 'Whether more users are available beyond this page',
    type: 'boolean',
  },
}"
    />

    #### TraitUser Object [#traituser-object]

    <TypeTable
      type="{
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  traits: {
    description: &#x22;The user's full traits map&#x22;,
    type: 'object',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  sessions: {
    description: 'Total number of sessions',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/user-traits/users',
            params={
                'key': 'plan',
                'value': 'pro'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/user-traits/users?key=plan&value=pro");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "users": [
        {
          "user_id": "a1b2c3",
          "identified_user_id": "user_987",
          "traits": { "plan": "pro", "company": "Acme" },
          "country": "US",
          "region": "California",
          "city": "CA-San Francisco",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "sessions": 14
        }
      ],
      "total": 1,
      "hasMore": false
    }
    ```
  </div>
</div>


# Get User Trait Values (/fr/docs/api/user-traits/values)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/user-traits/values
    ```

    Returns the distinct values for a given trait key, with user counts.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  key: {
    description: 'The trait key to list values for',
    type: 'string',
    required: true,
  },
  limit: {
    description: 'Maximum number of values to return',
    type: 'number',
    default: '1000',
  },
  offset: {
    description: 'Number of values to skip',
    type: 'number',
    default: '0',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  values: {
    description: 'Array of distinct trait values',
    type: 'TraitValue[]',
  },
  total: {
    description: 'Total number of distinct values',
    type: 'number',
  },
  hasMore: {
    description: 'Whether more values are available beyond this page',
    type: 'boolean',
  },
}"
    />

    #### TraitValue Object [#traitvalue-object]

    <TypeTable
      type="{
  value: {
    description: 'The trait value',
    type: 'string',
  },
  userCount: {
    description: 'Number of users with this value',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/user-traits/values?key=plan" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/user-traits/values?key=plan',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/user-traits/values',
            params={
                'key': 'plan'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/user-traits/values?key=plan');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/user-traits/values?key=plan')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/user-traits/values?key=plan", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/user-traits/values?key=plan")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/user-traits/values?key=plan"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/user-traits/values?key=plan");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "values": [
        { "value": "pro", "userCount": 340 },
        { "value": "free", "userCount": 900 }
      ],
      "total": 2,
      "hasMore": false
    }
    ```
  </div>
</div>


# Get User Info (/fr/docs/api/users/info)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/users/:userId
    ```

    Returns detailed information about a specific user, including their profile traits and linked devices.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  userId: {
    description: 'User ID (device fingerprint or identified user ID)',
    type: 'string',
    required: true,
  },
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'User info object',
    type: 'UserInfo',
  },
}"
    />

    #### UserInfo Object [#userinfo-object]

    <TypeTable
      type="{
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified',
    type: 'string',
  },
  traits: {
    description: 'Custom user traits/properties set via identify()',
    type: 'object | null',
  },
  sessions: {
    description: 'Total number of sessions',
    type: 'number',
  },
  pageviews: {
    description: 'Total pageviews',
    type: 'number',
  },
  events: {
    description: 'Total custom events',
    type: 'number',
  },
  duration: {
    description: 'Average session duration in seconds',
    type: 'number',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  language: {
    description: 'Browser language',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
  first_seen: {
    description: 'First activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  last_seen: {
    description: 'Most recent activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  timezone: {
    description: 'Timezone reported by the browser',
    type: 'string',
  },
  ip: {
    description: 'Last known IP address',
    type: 'string',
  },
  first_referrer: {
    description: 'Referrer URL of the first session',
    type: 'string',
  },
  first_channel: {
    description: 'Acquisition channel of the first session',
    type: 'string',
  },
  first_entry_page: {
    description: 'Entry page path of the first session',
    type: 'string',
  },
  first_utm_source: {
    description: 'UTM source of the first session',
    type: 'string',
  },
  first_utm_medium: {
    description: 'UTM medium of the first session',
    type: 'string',
  },
  first_utm_campaign: {
    description: 'UTM campaign of the first session',
    type: 'string',
  },
  last_referrer: {
    description: 'Referrer URL of the most recent session',
    type: 'string',
  },
  last_channel: {
    description: 'Acquisition channel of the most recent session',
    type: 'string',
  },
  vitals: {
    description: 'p75 Core Web Vitals for this user, or null when no performance data exists',
    type: 'UserVitals | null',
  },
  locations: {
    description: 'Per-location breakdown of sessions',
    type: 'UserLocation[]',
  },
  devices: {
    description: 'Per-device breakdown of sessions',
    type: 'UserDevice[]',
  },
  linked_devices: {
    description: 'Devices linked to this identified user',
    type: 'LinkedDevice[]',
  },
}"
    />

    #### UserVitals Object [#uservitals-object]

    <TypeTable
      type="{
  lcp_p75: {
    description: 'p75 Largest Contentful Paint (ms)',
    type: 'number | null',
  },
  cls_p75: {
    description: 'p75 Cumulative Layout Shift',
    type: 'number | null',
  },
  inp_p75: {
    description: 'p75 Interaction to Next Paint (ms)',
    type: 'number | null',
  },
  fcp_p75: {
    description: 'p75 First Contentful Paint (ms)',
    type: 'number | null',
  },
  ttfb_p75: {
    description: 'p75 Time to First Byte (ms)',
    type: 'number | null',
  },
  performance_events: {
    description: 'Number of performance events collected',
    type: 'number',
  },
}"
    />

    #### UserLocation Object [#userlocation-object]

    <TypeTable
      type="{
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  sessions: {
    description: 'Number of sessions from this location',
    type: 'number',
  },
  last_seen: {
    description: 'Most recent activity from this location',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />

    #### UserDevice Object [#userdevice-object]

    <TypeTable
      type="{
  device_type: {
    description: 'Device type',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  browser_version: {
    description: 'Browser version',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  operating_system_version: {
    description: 'Operating system version',
    type: 'string',
  },
  screen_width: {
    description: 'Screen width in pixels',
    type: 'number',
  },
  screen_height: {
    description: 'Screen height in pixels',
    type: 'number',
  },
  sessions: {
    description: 'Number of sessions on this device',
    type: 'number',
  },
  last_seen: {
    description: 'Most recent activity on this device',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />

    #### LinkedDevice Object [#linkeddevice-object]

    <TypeTable
      type="{
  anonymous_id: {
    description: 'Anonymous device fingerprint',
    type: 'string',
  },
  created_at: {
    description: 'When the device was linked',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/123/users/user@example.com" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/123/users/user@example.com',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/123/users/user@example.com',
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/123/users/user@example.com');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/123/users/user@example.com')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/123/users/user@example.com", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/123/users/user@example.com")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/123/users/user@example.com"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/users/user@example.com");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": {
        "user_id": "abc123def456",
        "identified_user_id": "user@example.com",
        "traits": {
          "name": "John Doe",
          "plan": "pro",
          "company": "Acme Inc"
        },
        "sessions": 12,
        "pageviews": 156,
        "events": 23,
        "duration": 245,
        "country": "US",
        "region": "California",
        "city": "San Francisco",
        "language": "en-US",
        "browser": "Chrome",
        "browser_version": "120.0.0",
        "operating_system": "macOS",
        "operating_system_version": "14.2",
        "device_type": "desktop",
        "screen_width": 2560,
        "screen_height": 1440,
        "first_seen": "2024-01-15T10:30:00.000Z",
        "last_seen": "2024-01-31T14:22:00.000Z",
        "timezone": "America/Los_Angeles",
        "ip": "203.0.113.42",
        "first_referrer": "https://google.com",
        "first_channel": "Organic Search",
        "first_entry_page": "/pricing",
        "first_utm_source": "google",
        "first_utm_medium": "cpc",
        "first_utm_campaign": "launch",
        "last_referrer": "https://twitter.com",
        "last_channel": "Social",
        "vitals": {
          "lcp_p75": 1240,
          "cls_p75": 0.02,
          "inp_p75": 180,
          "fcp_p75": 890,
          "ttfb_p75": 210,
          "performance_events": 48
        },
        "locations": [
          {
            "country": "US",
            "region": "California",
            "city": "San Francisco",
            "sessions": 10,
            "last_seen": "2024-01-31T14:22:00.000Z"
          }
        ],
        "devices": [
          {
            "device_type": "desktop",
            "browser": "Chrome",
            "browser_version": "120.0.0",
            "operating_system": "macOS",
            "operating_system_version": "14.2",
            "screen_width": 2560,
            "screen_height": 1440,
            "sessions": 9,
            "last_seen": "2024-01-31T14:22:00.000Z"
          }
        ],
        "linked_devices": [
          {
            "anonymous_id": "xyz789ghi012",
            "created_at": "2024-01-20T08:15:00.000Z"
          }
        ]
      }
    }
    ```
  </div>
</div>


# Get Users (/fr/docs/api/users/list)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/users
    ```

    Returns a paginated list of users with their analytics data. Supports filtering by identified users only.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) plus the following:

    <TypeTable
      type="{
  page: {
    description: 'Page number (1-indexed)',
    type: 'number',
    default: 1,
  },
  page_size: {
    description: 'Number of results per page',
    type: 'number',
    default: 100,
  },
  sort_by: {
    description: 'Field to sort by',
    type: 'string',
    typeDescription: '&#x22;first_seen&#x22; | &#x22;last_seen&#x22; | &#x22;pageviews&#x22; | &#x22;sessions&#x22; | &#x22;events&#x22;',
    default: 'last_seen',
  },
  sort_order: {
    description: 'Sort direction',
    type: 'string',
    typeDescription: '&#x22;asc&#x22; | &#x22;desc&#x22;',
    default: 'desc',
  },
  identified_only: {
    description: 'Only return users with a custom identified_user_id',
    type: 'string',
    typeDescription: '&#x22;true&#x22; | &#x22;false&#x22;',
    default: 'false',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of user objects',
    type: 'User[]',
  },
  totalCount: {
    description: 'Total number of users across all pages',
    type: 'number',
  },
  page: {
    description: 'Current page number',
    type: 'number',
  },
  pageSize: {
    description: 'Number of results per page',
    type: 'number',
  },
}"
    />

    #### User Object [#user-object]

    <TypeTable
      type="{
  user_id: {
    description: 'Device fingerprint identifier',
    type: 'string',
  },
  identified_user_id: {
    description: 'Custom user ID when identified, empty string otherwise',
    type: 'string',
  },
  traits: {
    description: 'Custom user traits/properties',
    type: 'object | null',
  },
  country: {
    description: 'Country code',
    type: 'string',
  },
  region: {
    description: 'Region/state',
    type: 'string',
  },
  city: {
    description: 'City name',
    type: 'string',
  },
  language: {
    description: 'Browser language',
    type: 'string',
  },
  browser: {
    description: 'Browser name',
    type: 'string',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
  },
  device_type: {
    description: 'Device type (desktop, mobile, tablet)',
    type: 'string',
  },
  pageviews: {
    description: 'Total pageviews by this user',
    type: 'number',
  },
  events: {
    description: 'Total custom events by this user',
    type: 'number',
  },
  sessions: {
    description: 'Total sessions by this user',
    type: 'number',
  },
  hostname: {
    description: 'First hostname visited',
    type: 'string',
  },
  first_seen: {
    description: 'First activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
  last_seen: {
    description: 'Most recent activity timestamp',
    type: 'string',
    typeDescription: 'ISO 8601 datetime',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/users',
            params={
                'page': 1,
                'page_size': 10,
                'sort_by': 'last_seen',
                'sort_order': 'desc'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/users?page=1&page_size=10&sort_by=last_seen&sort_order=desc");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "user_id": "abc123def456",
          "identified_user_id": "user@example.com",
          "traits": {
            "plan": "pro",
            "company": "Acme Inc"
          },
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "language": "en-US",
          "browser": "Chrome",
          "operating_system": "macOS",
          "device_type": "desktop",
          "pageviews": 156,
          "events": 23,
          "sessions": 12,
          "hostname": "example.com",
          "first_seen": "2024-01-15T10:30:00.000Z",
          "last_seen": "2024-01-31T14:22:00.000Z"
        }
      ],
      "totalCount": 1247,
      "page": 1,
      "pageSize": 10
    }
    ```
  </div>
</div>


# Get User Session Count (/fr/docs/api/users/session-count)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    GET /api/sites/:site/users/session-count
    ```

    Returns the number of sessions per day for a specific user. Useful for visualizing user engagement over time.

    ### Path Parameters [#path-parameters]

    <TypeTable
      type="{
  site: {
    description: 'Site ID or site identifier',
    type: 'string | number',
    required: true,
  },
}"
    />

    ### Query Parameters [#query-parameters]

    <TypeTable
      type="{
  user_id: {
    description: 'User ID (device fingerprint or identified user ID)',
    type: 'string',
    required: true,
  },
  time_zone: {
    description: 'Timezone for date grouping',
    type: 'string',
    default: 'UTC',
    typeDescription: 'IANA timezone (e.g., &#x22;America/New_York&#x22;)',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  data: {
    description: 'Array of daily session counts',
    type: 'DailyCount[]',
  },
}"
    />

    #### DailyCount Object [#dailycount-object]

    <TypeTable
      type="{
  date: {
    description: 'Date',
    type: 'string',
    typeDescription: 'YYYY-MM-DD format',
  },
  sessions: {
    description: 'Number of sessions on this date',
    type: 'number',
  },
}"
    />
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X GET "https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York" \
          -H "Authorization: Bearer your_api_key_here"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch(
          'https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York',
          {
            headers: {
              'Authorization': 'Bearer your_api_key_here'
            }
          }
        );

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests

        response = requests.get(
            'https://app.rybbit.io/api/sites/1/users/session-count',
            params={
                'user_id': 'abc123def456',
                'time_zone': 'America/New_York'
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York')
        req = Net::HTTP::Get.new(uri)
        req['Authorization'] = 'Bearer your_api_key_here'

        res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
        data = JSON.parse(res.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        req, _ := http.NewRequest("GET", "https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York", nil)
        req.Header.Set("Authorization", "Bearer your_api_key_here")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let client = reqwest::Client::new();
        let res = client
            .get("https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York")
            .header("Authorization", "Bearer your_api_key_here")
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York"))
            .header("Authorization", "Bearer your_api_key_here")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/users/session-count?user_id=abc123def456&time_zone=America/New_York");
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Response"
    {
      "data": [
        {
          "date": "2024-01-15",
          "sessions": 2
        },
        {
          "date": "2024-01-18",
          "sessions": 1
        },
        {
          "date": "2024-01-22",
          "sessions": 3
        },
        {
          "date": "2024-01-31",
          "sessions": 1
        }
      ]
    }
    ```
  </div>
</div>


# Gatsby (/fr/docs/guides/react/gatsby)





Gatsby generates the `<head>` of every page at build time. Add the snippet through the `onRenderBody` API in `gatsby-ssr.js`, or with Gatsby's own `<Script>` component if you want control over load timing.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Gatsby [#add-the-snippet-to-gatsby]

    <Tabs items="[&#x22;gatsby-ssr.js&#x22;, &#x22;Gatsby Script component&#x22;]">
      <Tab value="gatsby-ssr.js">
        Create `gatsby-ssr.js` at the root of your project if it does not exist and register the script with `setHeadComponents`:

        ```javascript title="gatsby-ssr.js"
        import React from "react";

        export const onRenderBody = ({ setHeadComponents }) => {
          setHeadComponents([
            <script
              key="rybbit-analytics"
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              defer
            />,
          ]);
        };
        ```

        This puts the tag in the `<head>` of every generated page.
      </Tab>

      <Tab value="Gatsby Script component">
        The [Gatsby Script API](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-script/) loads third-party scripts with a chosen `strategy` (`post-hydrate`, `idle` or `off-main-thread`). Render it in a layout component that wraps every page:

        ```jsx title="src/components/layout.js"
        import React from "react";
        import { Script } from "gatsby";

        export default function Layout({ children }) {
          return (
            <>
              {children}
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="post-hydrate"
              />
            </>
          );
        }
        ```
      </Tab>
    </Tabs>

    Rebuild the site (`gatsby build`) and deploy the `public` folder. Client-side navigation through Gatsby's `<Link>` is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any React component. Guard the call, because Gatsby renders components on the server during the build.

```jsx title="src/components/TrackedButton.js"
import React from "react";

export default function TrackedButton({ label, eventName, eventData }) {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event(eventName, eventData);
    }
  };

  return <button onClick={handleClick}>{label}</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after client-side navigation**: this is rare. If it happens, export `onRouteUpdate` from `gatsby-browser.js` and call `window.rybbit.pageview()` there when `location.pathname` changes. Test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Next.js (/fr/docs/guides/react/next-js)





Next.js ships a [Script component](https://nextjs.org/docs/app/building-your-application/optimizing/scripts) that controls when a third-party script loads. Render it once in your root layout (App Router) or custom `App` (Pages Router) so the snippet is on every page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Next.js [#add-the-snippet-to-nextjs]

    Use `next/script` with `strategy="afterInteractive"` instead of a plain `<script>` tag. The `defer` attribute from the snippet is not needed; the strategy handles load timing.

    <Tabs items="[&#x22;App Router&#x22;, &#x22;Pages Router&#x22;]">
      <Tab value="App Router">
        ```jsx title="app/layout.js"
        import Script from "next/script";

        export default function RootLayout({ children }) {
          return (
            <html lang="en">
              <body>
                {children}
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```
      </Tab>

      <Tab value="Pages Router">
        ```jsx title="pages/_app.js"
        import Script from "next/script";

        export default function MyApp({ Component, pageProps }) {
          return (
            <>
              <Component {...pageProps} />
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </>
          );
        }
        ```
      </Tab>
    </Tabs>

    Client-side navigation through `<Link>` and `router.push()` is tracked automatically as pageviews; no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any client component. Guard the call, because the script loads after hydration and components can also render on the server.

```jsx title="components/MyButton.js"
"use client";

export default function MyButton({ title }) {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("button_click", { buttonTitle: title });
    }
  };

  return <button onClick={handleClick}>{title}</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Proxying through your own domain**: Next.js [rewrites](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites) can serve the script and its API from your domain. Follow the [Next.js proxy guide](/docs/proxy-guide/next-js); every endpoint must be rewritten, including `site/tracking-config`, otherwise the script silently falls back to default settings and features such as web vitals and session replay stay off.
* **Pageviews missing after client-side navigation**: this is rare; call `window.rybbit.pageview()` yourself after the route change only if the default behaviour does not work for you.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# React Router (/fr/docs/guides/react/react-router)





In React Router framework mode (v7 and later, the successor to Remix), `app/root.tsx` renders the `<html>` document for every route. Add the snippet to the `<head>` in its `Layout` export. This guide supersedes the [Remix guide](/docs/guides/react/remix); if you use React Router only as a library inside a Vite app, follow the [React (Vite / CRA) guide](/docs/guides/react/vite-cra) instead.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to React Router [#add-the-snippet-to-react-router]

    Open `app/root.tsx` and add the tag inside `<head>` of the `Layout` component, after `<Meta />` and `<Links />`. `Layout` wraps the app, `HydrateFallback` and `ErrorBoundary`, so the snippet stays in place in every state:

    ```tsx title="app/root.tsx"
    import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";

    export function Layout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <Meta />
            <Links />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            {children}
            <ScrollRestoration />
            <Scripts />
          </body>
        </html>
      );
    }

    export default function App() {
      return <Outlet />;
    }
    ```

    If your `root.tsx` has no `Layout` export, add the tag to the `<head>` of the default `App` component instead. Restart the dev server after the change. Client-side navigation through `<Link>` and `useNavigate()` is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any route or component. Check for `window` first, because route modules also render on the server.

```tsx title="app/routes/pricing.tsx"
export default function Pricing() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("plan_selected", { plan: "pro" });
    }
  };

  return <button onClick={handleClick}>Choose Pro</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Nonce-based Content Security Policy**: if you pass a `nonce` to `<Scripts />` and `<ScrollRestoration />`, add the same `nonce` attribute to the Rybbit tag, otherwise the browser blocks it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Remix (/fr/docs/guides/react/remix)





Remix renders the whole HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file and reaches every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Remix [#add-the-snippet-to-remix]

    Open `app/root.tsx` (or `app/root.jsx`) and add the tag inside `<head>`, after `<Meta />` and `<Links />`:

    ```tsx title="app/root.tsx"
    import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "@remix-run/react";

    export default function App() {
      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <Meta />
            <Links />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            <Outlet />
            <ScrollRestoration />
            <Scripts />
          </body>
        </html>
      );
    }
    ```

    Restart the dev server after the change. Client-side navigation after the initial server render is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any route or component. Check for `window` first, because Remix renders components on the server.

```tsx title="app/routes/offer.tsx"
export default function OfferRoute() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("offer_claimed", { feature: "Special Offer" });
    }
  };

  return <button onClick={handleClick}>Claim Offer</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after client-side navigation**: this is rare. If it happens, call `window.rybbit.pageview()` from a root-level effect that runs on `useLocation()` changes; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# TanStack Start (/fr/docs/guides/react/tanstack-start)





TanStack Start manages the document head through the root route's `head()` option, rendered by `<HeadContent />` in `src/routes/__root.tsx`. Add the snippet to the `scripts` array returned by `head()` and it is on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to TanStack Start [#add-the-snippet-to-tanstack-start]

    Open `src/routes/__root.tsx` and add a `scripts` entry to the object returned by `head()`. `<HeadContent />` in the root document renders it as a `<script>` tag inside `<head>`:

    ```tsx title="src/routes/__root.tsx"
    import type { ReactNode } from "react";
    import { Outlet, createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";

    export const Route = createRootRoute({
      head: () => ({
        meta: [
          { charSet: "utf-8" },
          { name: "viewport", content: "width=device-width, initial-scale=1" },
          { title: "My App" },
        ],
        scripts: [
          {
            src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
            defer: true,
          },
        ],
      }),
      component: RootComponent,
    });

    function RootComponent() {
      return (
        <RootDocument>
          <Outlet />
        </RootDocument>
      );
    }

    function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
      return (
        <html>
          <head>
            <HeadContent />
          </head>
          <body>
            {children}
            <Scripts />
          </body>
        </html>
      );
    }
    ```

    Use the `scripts` key inside `head()`, not the route-level `scripts` option: that one renders body scripts through `<Scripts />`, which also works but loads later. Client-side navigation through `<Link>` and `useNavigate()` is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any route component. Check for `window` first, because TanStack Start renders routes on the server by default.

```tsx title="src/routes/pricing.tsx"
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/pricing")({
  component: Pricing,
});

function Pricing() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("plan_selected", { plan: "pro" });
    }
  };

  return <button onClick={handleClick}>Choose Pro</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# React (Vite / CRA) (/fr/docs/guides/react/vite-cra)





A client-side React app built with Vite or Create React App has a single HTML entry file. Paste the snippet into its `<head>` and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to React [#add-the-snippet-to-react]

    Find the HTML entry file for your tooling:

    * **Vite**: `index.html` at the project root.
    * **Create React App**: `public/index.html`.

    Paste the snippet just before `</head>`:

    ```html title="index.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <title>My React App</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="root"></div>
      </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Route changes made by React Router and similar libraries are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw.

```jsx title="src/components/LearnMoreButton.jsx"
export default function LearnMoreButton() {
  const handleClick = () => {
    if (window.rybbit) {
      window.rybbit.event("button_click", { category: "CTA", label: "Learn More" });
    }
  };

  return <button onClick={handleClick}>Learn More</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: this is rare with React Router. If it happens, call `window.rybbit.pageview()` after each route change; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# SvelteKit (/fr/docs/guides/svelte/sveltekit)





SvelteKit renders every page through a single HTML shell at `src/app.html`, so adding the snippet there loads Rybbit on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to SvelteKit [#add-the-snippet-to-sveltekit]

    Open `src/app.html` and paste the snippet inside `<head>`, next to `%sveltekit.head%`:

    ```html title="src/app.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <link rel="icon" href="%sveltekit.assets%/favicon.png" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        %sveltekit.head%
      </head>
      <body data-sveltekit-preload-data="hover">
        <div style="display: contents">%sveltekit.body%</div>
      </body>
    </html>
    ```

    Rybbit tracks SvelteKit's client-side navigations as pageviews automatically; no router hook is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any Svelte component. Guard the call with `typeof window !== "undefined"`, since SvelteKit components also run on the server:

```svelte title="src/lib/components/ActionButton.svelte"
<script>
  function handleAction() {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("user_action", { component: "ActionButton" });
    }
  }
</script>

<button on:click={handleAction}>Perform action</button>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: automatic route tracking covers SvelteKit's router, so test the default first. If a navigation is still not recorded, trigger it from `afterNavigate` in your root layout:

  ```svelte title="src/routes/+layout.svelte"
  <script>
    import { afterNavigate } from "$app/navigation";

    afterNavigate(() => {
      if (typeof window !== "undefined" && window.rybbit) {
        window.rybbit.pageview();
      }
    });
  </script>
  ```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Svelte (Vite / Client-Side) (/fr/docs/guides/svelte/vite)





A client-side Svelte app built with Vite (`npm create vite@latest -- --template svelte`) serves a single `index.html` at the project root. Add the snippet there and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Svelte [#add-the-snippet-to-svelte]

    Open `index.html` at the root of your project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Svelte App</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/main.js"></script>
      </body>
    </html>
    ```

    Placing it just before `</body>` also works, but `<head>` lets the script start loading sooner.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any Svelte component:

```svelte title="src/lib/ActionButton.svelte"
<script>
  function handleAction() {
    if (window.rybbit) {
      window.rybbit.event("user_action", { component: "ActionButton" });
    }
  }
</script>

<button on:click={handleAction}>Perform action</button>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: Rybbit tracks History API and hash navigations, which covers routers such as `svelte-routing` and `svelte-spa-router`. If a route change is still not recorded, call `window.rybbit.pageview()` from that router's navigation callback.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Nuxt.js (/fr/docs/guides/vue/nuxt)





Nuxt has two ways to load Rybbit: the [Nuxt Scripts](https://scripts.nuxt.com/scripts/rybbit-analytics) module, which ships a first-class Rybbit registry entry with a typed composable, or the `app.head.script` array in `nuxt.config.ts`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Nuxt [#add-the-snippet-to-nuxt]

    <Tabs items="[&#x22;Nuxt Scripts (Nuxt 3 and 4)&#x22;, &#x22;nuxt.config head&#x22;]">
      <Tab value="Nuxt Scripts (Nuxt 3 and 4)">
        Install the module. This adds `@nuxt/scripts` to the `modules` array in your `nuxt.config`:

        ```bash
        npx nuxi module add scripts
        ```

        Register Rybbit under `scripts.registry` with the site ID from your snippet:

        ```typescript title="nuxt.config.ts"
        export default defineNuxtConfig({
          modules: ["@nuxt/scripts"],
          scripts: {
            registry: {
              rybbitAnalytics: {
                siteId: "YOUR_SITE_ID",
                trigger: "onNuxtReady",
              },
            },
          },
        });
        ```

        Options:

        * `siteId` (required): your Rybbit site ID.
        * `autoTrackPageview`: track pageviews automatically (on by default).
        * `trackSpa`: track client-side route changes (on by default).
        * `analyticsHost`: script and API host for a self-hosted instance, for example `https://your-instance.com/api`.
        * `sessionReplay`, `webVitals`, `trackOutbound`: optional features.

        <Callout type="info">
          To keep the site ID out of source control, leave `siteId` unset and provide `NUXT_PUBLIC_SCRIPTS_RYBBIT_ANALYTICS_SITE_ID` in the environment; Nuxt Scripts reads it at runtime.
        </Callout>
      </Tab>

      <Tab value="nuxt.config head">
        Add the script to the `app.head.script` array in `nuxt.config.ts`:

        ```typescript title="nuxt.config.ts"
        export default defineNuxtConfig({
          app: {
            head: {
              script: [
                {
                  src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                  defer: true,
                },
              ],
            },
          },
        });
        ```

        On Nuxt 2 the array is `head.script` at the top level of `nuxt.config.js`, with the same entry.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

With Nuxt Scripts, use the `useScriptRybbitAnalytics` composable. Its `proxy` queues calls until the script is ready, so it is safe to call immediately:

```vue title="components/ActionButton.vue"
<template>
  <button @click="handleAction">Track action</button>
</template>

<script setup>
const { proxy } = useScriptRybbitAnalytics();

function handleAction() {
  proxy.event("nuxt_interaction", { detail: "User clicked the action button" });
}
</script>
```

With the `app.head.script` method, call `window.rybbit` directly and guard it with `import.meta.client`, since components also run on the server (on Nuxt 2 use `process.client`):

```vue title="components/ActionButton.vue"
<template>
  <button @click="handleAction">Track action</button>
</template>

<script setup>
function handleAction() {
  if (import.meta.client && window.rybbit) {
    window.rybbit.event("nuxt_interaction", { detail: "User clicked the action button" });
  }
}
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: both methods track Nuxt's client-side route changes automatically, so test the default first. If a route change is still not recorded, call `window.rybbit.pageview()` from a `router.afterEach` hook in a client plugin.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Vue.js (Vite / Client-Side) (/fr/docs/guides/vue/vite)





A client-side Vue app built with Vite (`npm create vue@latest` or `npm create vite@latest -- --template vue`) serves a single `index.html` at the project root. Add the snippet there and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Vue.js [#add-the-snippet-to-vuejs]

    Open `index.html` at the root of your project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" href="/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Vue App</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/main.js"></script>
      </body>
    </html>
    ```

    Placing it just before `</body>` also works, but `<head>` lets the script start loading sooner.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component or method:

```vue title="src/components/ActionButton.vue"
<template>
  <button @click="trackAction">Track action</button>
</template>

<script setup>
function trackAction() {
  if (window.rybbit) {
    window.rybbit.event("custom_vue_action", { detail: "User performed an action" });
  }
}
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: Rybbit tracks Vue Router navigations automatically, so test the default first. If a route change is still not recorded, trigger it from an `afterEach` guard in your router setup:

  ```javascript title="src/router/index.js"
  import { createRouter, createWebHistory } from "vue-router";

  const router = createRouter({
    history: createWebHistory(import.meta.env.BASE_URL),
    routes: [/* your routes */],
  });

  router.afterEach(() => {
    if (window.rybbit) {
      window.rybbit.pageview();
    }
  });

  export default router;
  ```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Account settings (/zh/docs/account-settings)







Access your account settings by clicking on "Account" or going to [app.rybbit.io/settings/account](https://app.rybbit.io/settings/account).

<img alt="account settings" src="__img0" />

## Account [#account]

### Name [#name]

Update your display name shown across the platform. This name is visible to other members in your organization.

### Email [#email]

Update your email address for account notifications and login. This is the primary email associated with your account.

### Weekly Email Reports <span className="text-green-500 text-sm">(Cloud)</span> [#weekly-email-reports-cloud]

Enable or disable automatic weekly email reports. When enabled, you'll receive a summary of your analytics performance delivered to your inbox each week.

### Sign Out [#sign-out]

Sign out of your current session.

## Security [#security]

### Change Password [#change-password]

Update your password to keep your account secure.

### Delete Account [#delete-account]

Permanently delete your account and all associated data.

<Callout type="warn">
  This action cannot be undone. If you have an active subscription, you must cancel it before deleting your account.
</Callout>

## API Keys [#api-keys]

Generate API keys to access Rybbit's analytics endpoints from your applications.

### Creating an API Key [#creating-an-api-key]

1. Enter a name for your API key (e.g., "Production App", "Development")
2. Optionally enable **Restrict permissions** to limit the key to specific resources. Leave it off for a full-access key that can do everything you can.
3. Click "Create"
4. Copy and save the generated key immediately

<Callout type="warn">
  On Rybbit Cloud, API keys require a Standard or Pro plan. On a free plan you'll see an upgrade prompt in place of the creation form.
</Callout>

<Callout type="warn">
  API keys are only shown once when created. Store your key securely as you won't be able to view it again.
</Callout>

### Managing API Keys [#managing-api-keys]

Your existing API keys are displayed in a table showing:

* **Name** - The name you assigned to the key
* **Key** - A preview of the key (first few characters)
* **Permissions** - Whether the key has full access or is restricted to specific scopes
* **Created** - When the key was created
* **Last used** - When the key last made a request

You can delete API keys that are no longer needed. Deleting a key immediately revokes access for any applications using it.

### Using API Keys [#using-api-keys]

Include your API key in requests to Rybbit's API endpoints. See the [API documentation](/docs/api) for available endpoints and usage examples.


# Autocapture (/zh/docs/autocapture)



Rybbit can automatically capture common user interactions without requiring any code changes. These features can be enabled in your [Site Settings](/docs/site-settings) under the "Auto Capture" section.

## Available Autocapture Features [#available-autocapture-features]

| Feature           | Description                              | Event Type                    |
| ----------------- | ---------------------------------------- | ----------------------------- |
| Outbound Links    | Track clicks on external links           | `outbound`                    |
| Error Tracking    | Capture JavaScript errors and exceptions | `error`                       |
| Button Clicks     | Track clicks on buttons                  | `button_click`                |
| Copy Events       | Track when users copy text               | `copy`                        |
| Form Interactions | Track form submissions and input changes | `form_submit`, `input_change` |

## Outbound Links [#outbound-links]

When enabled, Rybbit automatically tracks clicks on links that navigate to external domains.

**Tracked properties:**

* `url` - The destination URL
* `text` - The link text
* `target` - The link target attribute (e.g., `_blank`, `_self`)

## Error Tracking [#error-tracking]

Captures uncaught JavaScript errors and unhandled promise rejections from your site. Only errors originating from your domain are tracked (third-party script errors are filtered out).

**Tracked properties:**

* `message` - The error message
* `stack` - Stack trace (truncated to 2000 characters)
* `fileName` - Source file where the error occurred
* `lineNumber` - Line number
* `columnNumber` - Column number

## Button Clicks [#button-clicks]

Automatically tracks clicks on:

* `<button>` elements
* Elements with `role="button"`
* `<input type="submit">` and `<input type="button">`

**Tracked properties:**

* `text` - The button's text content (falls back to `aria-label`, then `value` for input buttons, then `title`)

### Adding Custom Properties [#adding-custom-properties]

You can add custom properties to auto-tracked button clicks using `data-rybbit-prop-*` attributes:

```html
<button
  data-rybbit-prop-category="pricing"
  data-rybbit-prop-variant="blue"
>
  Buy Now
</button>
```

This tracks: `{ text: "Buy Now", category: "pricing", variant: "blue" }`

### Skipping Autocapture for Specific Buttons [#skipping-autocapture-for-specific-buttons]

If you want to track a button with a custom event instead of the automatic `button_click`, add the `data-rybbit-event` attribute:

```html
<!-- This button will fire a custom "signup" event, NOT a button_click -->
<button data-rybbit-event="signup" data-rybbit-prop-plan="pro">
  Sign Up
</button>
```

See [Track Events](/docs/track-events) for more details on custom event tracking.

## Copy Events [#copy-events]

Tracks when users copy text from your site using Ctrl+C, Cmd+C, or the context menu.

**Tracked properties:**

* `text` - The copied text (truncated to 500 characters)
* `textLength` - Original length of the copied text (only included if text was truncated)
* `sourceElement` - The HTML tag where the text was copied from (e.g., `p`, `div`, `span`)

## Form Interactions [#form-interactions]

Tracks two types of form events:

### Form Submissions (`form_submit`) [#form-submissions-form_submit]

Triggered when a form is submitted.

**Tracked properties:**

* `formId` - The form's `id` attribute
* `formName` - The form's `name` attribute
* `formAction` - The form's `action` URL
* `method` - HTTP method (GET, POST, etc.)
* `fieldCount` - Number of form fields
* `ariaLabel` - The form's `aria-label` attribute (if present)

You can add custom properties using `data-rybbit-prop-*` on the form element:

```html
<form
  id="signup"
  data-rybbit-prop-form-type="registration"
  data-rybbit-prop-variant="a"
>
  ...
</form>
```

### Input Changes (`input_change`) [#input-changes-input_change]

Triggered when a user changes the value of an input, select, or textarea field. Disabled inputs are automatically excluded from tracking.

**Tracked properties:**

* `element` - The element type (`input`, `select`, or `textarea`)
* `inputType` - For inputs: the type attribute (e.g., `text`, `email`, `checkbox`)
* `inputName` - The field's `name`, `id`, `aria-label`, or `placeholder` attribute (first available)
* `formId` - The parent form's `id` (if within a form)
* `formName` - The parent form's `name` (if within a form)

You can add custom properties using `data-rybbit-prop-*` on the input element:

```html
<input
  name="email"
  data-rybbit-prop-field-category="contact"
/>

<select
  name="country"
  data-rybbit-prop-section="demographics"
>
  ...
</select>
```

**Privacy note:** Hidden inputs, password fields, and disabled inputs are automatically excluded from tracking.

## Enabling Autocapture [#enabling-autocapture]

1. Go to your site's **Settings**
2. Navigate to the **Auto Capture** section
3. Toggle on the features you want to enable

Changes take effect immediately for new visitors. Existing sessions may need to refresh to pick up the new configuration.

***

**Related Documentation:**

* [Track Events](/docs/track-events) - Manual event tracking
* [Site Settings](/docs/site-settings) - Configure your site
* [Behavior Analytics - Events](/docs/behavior-analytics/events) - View captured events


# Billing (/zh/docs/billing-settings)





Access billing settings by hovering over the sidebar and clicking "Billing".

Subscriptions are scoped to a single organization. If you have multiple organizations, each one requires its own subscription. Switching organizations will show that organization's subscription status.


# Bot detection (/zh/docs/bot-detection)





Rybbit can filter bot traffic before it reaches your normal analytics. When **Block Bot Traffic** is enabled for a site, each incoming tracking request is checked by several detection layers. If any layer identifies the request as bot traffic, the request is excluded from the normal analytics tables and stored separately for bot traffic inspection.

## Enabling Bot Detection [#enabling-bot-detection]

Bot blocking is configured per site:

1. Open your site in the Rybbit dashboard
2. Go to **Site Settings**
3. Enable **Block Bot Traffic**

When this setting is off, Rybbit does not block requests based on bot detection.

## What Happens to Detected Bots [#what-happens-to-detected-bots]

Detected bot requests are not added to your normal analytics data. This keeps dashboard totals, reports, journeys, funnels, session lists, and usage metrics focused on human traffic.

Detected bot visits also do not count toward billable analytics usage. If bot blocking filters a request, you are not charged for that bot visit.

Rybbit still stores a compact bot event record so you can inspect what was filtered. Bot event records include route, device, location, ASN, and which detection layers matched.

## Detection Layers [#detection-layers]

Rybbit runs all detection layers before making a final decision. A request can match multiple layers, and the bot event records every layer that matched.

<Steps>
  <Step>
    ### User-Agent Patterns [#user-agent-patterns]

    The `ua_pattern` layer checks the request user-agent against known bot, crawler, AI agent, SEO tool, monitoring, social preview, framework, and headless browser patterns.

    Examples include:

    * Search engine crawlers
    * Headless browser user-agents
    * AI crawler and agent user-agents
    * SEO and monitoring tools
    * Script or framework HTTP clients
  </Step>

  <Step>
    ### Header Heuristics [#header-heuristics]

    The `header_heuristics` layer scores request headers for browser consistency.

    It looks for signals such as:

    * Missing browser headers
    * Suspicious fetch metadata
    * Inconsistent browser claims
    * Headless or automation-looking headers
    * Stale or unusual Chrome versions
    * Script/framework-style requests that do not look like normal browser traffic

    This layer is useful because many bots use a browser-like user-agent but do not send the full set of headers a real browser normally sends.
  </Step>

  <Step>
    ### Client Signals [#client-signals]

    The `client_signals` layer uses lightweight browser-side signals collected by the tracking script.

    Signals include:

    * Automation APIs
    * Zero or impossible window dimensions
    * Default automation viewport sizes such as `800x600` and `1024x768`
    * Suspicious outer window dimensions
    * Missing browser APIs
    * Missing Chrome globals
    * SwiftShader renderer signals
    * Empty plugin lists

    Rybbit combines these into a weighted score. Strong signals can identify bot traffic on their own, while weaker signals contribute supporting evidence.
  </Step>

  <Step>
    ### ASN and Network Signals [#asn-and-network-signals]

    The `bot_asn` layer uses ASN metadata from the resolved IP address.

    There are two kinds of ASN matches:

    * **Curated bot provider ASNs**: Known AI, scanner, and internet measurement providers can trigger bot detection directly.
    * **Generic hosting/datacenter ASNs**: Hosting ASNs are treated as supporting evidence. They are recorded when another bot layer also matches, but generic hosting ASN alone is not enough to block a request.

    This avoids filtering every legitimate visitor who happens to browse through a cloud, CDN, VPN, corporate gateway, or first-party proxy, while still preserving ASN context when other bot evidence exists.
  </Step>

  <Step>
    ### Rate and Anomaly Detection [#rate-and-anomaly-detection]

    The `rate_anomaly` layer watches for bursty or crawl-shaped behavior.

    It tracks short rolling windows for patterns such as:

    * Too many events from the same IP and user-agent
    * Too many events from the same IP
    * Too many distinct paths visited quickly
    * Too many different user-agents from one IP
    * Too many hostnames from one IP
    * High site-wide volume from one user-agent
    * Large volumes of requests missing client-side bot scores

    This layer is designed to catch fast crawlers, floods, and replayed tracking requests that may not have obvious user-agent or browser fingerprint signals.
  </Step>
</Steps>

## Bot Identity [#bot-identity]

Every detected bot carries the layers that caught it. Bots matched by one of Rybbit's curated user-agent patterns carry three more fields, which is what the Bots dashboard groups by:

| Field          | Example       | Meaning                                      |
| -------------- | ------------- | -------------------------------------------- |
| `bot_name`     | `GPTBot`      | The name the bot publishes in its user agent |
| `bot_operator` | `OpenAI`      | Who runs it                                  |
| `bot_purpose`  | `ai_training` | What the fetch is for                        |

A bot matched only by a broad pattern (`crawl`, `spider`) is still filtered, but has no published identity — those rows read as **Unnamed**, which is more useful than a guess.

### Purposes [#purposes]

`bot_purpose` answers a different question from `bot_category`. Category groups bots into families; purpose says what the operator does with the page, which is the distinction that matters for AI traffic:

| Purpose          | What it means                                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ai_training`    | Collecting pages to train a model. Sends no readers back. Examples: GPTBot, ClaudeBot, CCBot, Google-Extended, Bytespider                                       |
| `ai_search`      | Indexing pages so an assistant can cite them. Can send readers back. Examples: OAI-SearchBot, Claude-SearchBot, PerplexityBot                                   |
| `ai_agent`       | A person asked an assistant to open the page, and it fetched it there and then. Examples: ChatGPT-User, Claude-User, Perplexity-User, Google-Agent, Claude Code |
| `search`         | Classic search engine indexing                                                                                                                                  |
| `social_preview` | Link unfurling                                                                                                                                                  |
| `seo`            | Backlink, rank, and site-audit crawlers                                                                                                                         |
| `monitoring`     | Uptime, synthetic, and performance checks                                                                                                                       |
| `security`       | Scanners                                                                                                                                                        |
| `scripted`       | HTTP libraries and CLI clients                                                                                                                                  |
| `headless`       | Browser automation                                                                                                                                              |

Splitting the AI family in three is the point: a training crawler reading 4,000 pages and a person's assistant opening one page are both `category: ai`, but they mean opposite things for your site.

<Callout>
  These fields were added in a later release. Bot events recorded before then have empty identity fields and appear as **Unnamed** / **Unclassified**; nothing is backfilled.
</Callout>

## How Decisions Are Made [#how-decisions-are-made]

Rybbit does not stop at the first matching layer. It runs every layer, records all matches, and then makes one final decision.

A request is marked as bot traffic when at least one blocking layer matches. The resulting bot event includes boolean fields for each layer:

* User-agent pattern
* Header heuristics
* Client signals
* Bot ASN
* Rate anomaly

Because multiple layers can match the same request, per-layer bot counts can add up to more than the total number of bot requests.

## Server-Side Tracking [#server-side-tracking]

Requests sent to `/api/track` with `Authorization: Bearer <api key>` and a valid API key are treated as trusted server-side ingestion. Four of the five layers are skipped: the headers, the client signals, the network address, and the request rate all belong to your server, not to the visitor it is reporting, so scoring them would convict your own backend.

The user-agent layer still runs, on the `user_agent` you send. Nothing changes for ordinary backend events — a request reporting a real browser's user agent is tracked normally.

### Reporting crawlers that never run JavaScript [#reporting-crawlers-that-never-run-javascript]

Rybbit's tracker is JavaScript, so a crawler that fetches your HTML and executes nothing never reaches Rybbit at all. Most AI training crawlers work exactly that way, which is why the Bots dashboard carries a note about its own coverage.

If you want to see them, report them from the edge — middleware, a worker, or a reverse proxy — forwarding the real request's `user_agent`:

```json
{
  "site_id": "1",
  "hostname": "example.com",
  "pathname": "/pricing",
  "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.2; +https://openai.com/gptbot"
}
```

A forwarded crawler user agent is classified and lands in your bot events with full identity, rather than in your analytics as a phantom visitor.

<Callout type="warn">
  Do not expose API keys in browser JavaScript. API keys are only for server-side requests.
</Callout>

## Proxies and CDN Setups [#proxies-and-cdn-setups]

If you proxy Rybbit through Cloudflare Workers, AWS CloudFront, Nginx, Caddy, or another reverse proxy, forward the original visitor IP:

```txt
X-Forwarded-For: <visitor-ip>
X-Real-IP: <visitor-ip>
```

Also preserve the original `User-Agent`, `Referer`, and `Accept-Language` headers where possible.

If the proxy IP is sent instead of the visitor IP, traffic may be geolocated to the proxy location and may inherit the proxy provider's ASN.

See the [proxy troubleshooting guide](/docs/proxy-guide/troubleshooting) for examples.

## What Bot Detection Does Not Guarantee [#what-bot-detection-does-not-guarantee]

Bot detection improves analytics quality, but no bot filter is perfect.

Some sophisticated bots can look like normal browsers. Some legitimate users may browse through unusual network paths or constrained browser environments. Rybbit uses multiple layers to reduce both misses and false positives, but you should still interpret bot counts as an operational signal rather than an exact measurement of all automation on your site.


# Comparison (/zh/docs/comparison)





| Feature                           | Rybbit                                                             | GA4                                                                | Plausible                                                            | Cloudflare                                                         |
| --------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Open Source**                   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Self-Hosting**                  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />\* | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Cookieless & Privacy friendly** | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Advanced Maps**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Advanced Filters**              | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Limited</span>    | <span className="inline-flex items-center gap-1">Limited</span>      | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Web Vitals**                    | <span className="inline-flex items-center gap-1">Paid</span>       | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Session Details**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **User Profiles**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Session Replays**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Funnels**                       | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Paid</span>         | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **User Journeys**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Retention Analysis**            | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Goals & Events**                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Real-time Dashboard**           | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Custom Events (JSON)**          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <span className="inline-flex items-center gap-1">Limited</span>      | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Error Tracking**                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Public Dashboards**             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |
| **Organizations**                 | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />   | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> |
| **Frog 🐸**                       | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />    | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />  |

\* Plausible's Community Edition has very limited features compared to their cloud version


# Data Import (/zh/docs/data-import)





The data import feature allows you to migrate your historical analytics data from other platforms to Rybbit. This preserves your analytics history when switching from competitors, giving you a complete view of your data without losing valuable insights.

## Supported Platforms [#supported-platforms]

Currently, Rybbit supports importing data from:

* Umami
* Simple Analytics
* Plausible

Additional platforms may be added in the future based on user demand.

<Callout type="info">
  Umami and Simple Analytics are imported from a CSV export, while Plausible is imported from its ZIP export. The Import dialog automatically expects the correct file type for the platform you select.
</Callout>

## Plan Requirements [#plan-requirements]

### Cloud Version [#cloud-version]

| Plan     | Access          | Historical Window   | Monthly Event Limit |
| -------- | --------------- | ------------------- | ------------------- |
| Free     | ❌ Not available | -                   | -                   |
| Standard | ✅ Available     | 36 months (3 years) | Plan limit applies  |
| Pro      | ✅ Available     | 60 months (5 years) | Plan limit applies  |

### Self-Hosted Version [#self-hosted-version]

Self-hosted installations have **unlimited** access to data imports with no restrictions on:

* Historical data window (import data from any date)
* Event quotas (no monthly limits)
* Concurrent imports (no limit on active imports)

## Import Limits [#import-limits]

### Historical Data Windows [#historical-data-windows]

The historical data window determines how far back you can import data:

* **Standard plans**: Import data from the past 36 months (3 years)
* **Pro plans**: Import data from the past 60 months (5 years)
* **Self-hosted**: Unlimited - import data from any date

Events outside your plan's historical window will be automatically skipped during import.

### Event Quotas [#event-quotas]

Imported events count toward your monthly event limit:

* If you're close to your monthly limit, imports may be partially skipped
* Skipped events are counted and displayed in the import history
* Consider upgrading your plan if you need to import large amounts of data

### Concurrent Imports [#concurrent-imports]

For cloud users:

* **Maximum 1 active import per organization**
* New imports are blocked until the current one completes
* Maximum 2-hour timeout per import

Self-hosted users have no concurrent import restrictions.

## How to Import Data [#how-to-import-data]

<Steps>
  <Step>
    ### Export Data from Source Platform [#export-data-from-source-platform]

    **Umami:**

    1. Navigate to Settings → Data
    2. Export your data as CSV
    3. Ensure the export includes all required fields

    **Simple Analytics:**

    1. Go to your site settings
    2. Navigate to Export section
    3. Download your analytics data as CSV

    **Plausible:**

    1. Open your site's dashboard
    2. Use the CSV export option to download your data
    3. Keep the exported **ZIP** archive as-is — do not unzip it
  </Step>

  <Step>
    ### Navigate to Import Settings [#navigate-to-import-settings]

    1. Open your Rybbit dashboard
    2. Navigate to Site Settings
    3. Click on the **Import** tab
  </Step>

  <Step>
    ### Select Platform and Upload File [#select-platform-and-upload-file]

    1. Select your source platform from the dropdown
    2. Click "Choose File" and select your exported file (a **CSV** for Umami and Simple Analytics, or a **ZIP** for Plausible)
    3. Click the **Import** button

    <Callout type="warn">
      For very large imports (multiple GB), consider splitting your CSV into smaller files and importing them sequentially.
    </Callout>
  </Step>

  <Step>
    ### Monitor Import Progress [#monitor-import-progress]

    Your import will begin processing in the background. You can:

    * View the import status in the "Import History" section
    * Monitor the number of imported, skipped, and invalid events
    * Continue using Rybbit while the import runs

    <Callout type="info">
      Large imports may take several minutes to complete. The page will automatically refresh to show updated progress.
    </Callout>
  </Step>
</Steps>

## Import History [#import-history]

The Import History section displays all your past and current imports.

### Import Metrics [#import-metrics]

Each import shows three key metrics:

**Imported Events**

* Number of events successfully imported into Rybbit
* These events are now visible in your analytics dashboard

**Skipped Events**

* Events that were excluded during import
* Common reasons:
  * Outside your plan's historical data window
  * Would exceed your monthly event quota

**Invalid Events**

* Events that failed validation during import
* Common reasons:
  * Malformed CSV data
  * Missing required fields
  * Invalid date/time formats
  * Data type mismatches

<Callout type="warn">
  If you see a high number of invalid events, verify your CSV export matches the expected format for your platform.
</Callout>

### Managing Imports [#managing-imports]

**Deleting Completed Imports**

* Click the trash icon next to any completed import
* Confirm the deletion in the dialog
* This will permanently remove the import record **and all associated events** from your analytics
* Active imports cannot be deleted

<Callout type="error">
  Deleting an import removes all events that were imported. This action cannot be undone. Make sure you have a backup of your original CSV file.
</Callout>

## Troubleshooting [#troubleshooting]

### Events Skipped Due to Quota Limits [#events-skipped-due-to-quota-limits]

**Cause:** Importing the events would exceed your monthly event limit.

**Solution:**

* Wait until the next billing cycle when your quota resets
* Upgrade to a plan with a higher event limit
* Import smaller date ranges to stay within quota

### Events Skipped Due to Date Range [#events-skipped-due-to-date-range]

**Cause:** Events are older than your plan's historical data window.

**Solution:**

* Upgrade to Pro plan for 60-month history (vs 24-month on Standard)
* For self-hosted, no action needed - all dates are allowed
* Filter your CSV export to only include recent data

### High Invalid Event Count [#high-invalid-event-count]

**Cause:** CSV format doesn't match the expected structure for your platform.

**Solution:**

1. Verify you selected the correct platform
2. Check that your CSV export includes all required fields
3. Look for special characters or malformed data in the CSV
4. Try importing a small sample file (first 100 rows) to test

### Import Appears Stuck [#import-appears-stuck]

**Cause:** Very large files can take time to process, or a timeout occurred.

**Solution:**

* Wait up to 2 hours for the import to complete
* If still stuck after 2 hours, the import will be automatically marked as complete
* Check the imported event count to see if any data was processed
* Contact support if no events were imported

## Best Practices [#best-practices]

### Before You Import [#before-you-import]

1. **Export a complete backup** from your current analytics platform
2. **Test with a small sample** (first 1,000 rows) before importing your full dataset
3. **Check your event quota** to ensure you have sufficient capacity
4. **Verify date ranges** match your plan's historical window
5. **Review CSV format** matches the required structure for your platform

### During Import [#during-import]

1. **Don't close the browser tab**
2. **Monitor the progress** in the Import History section
3. **Check for skipped/invalid events** early to catch format issues
4. **Wait for completion** before starting another import (cloud users)

### After Import [#after-import]

1. **Verify your data** appears correctly in analytics dashboards
2. **Check date ranges** to ensure historical data is visible
3. **Compare totals** with your source platform to validate accuracy
4. **Keep the original CSV** as a backup before deleting the import


# Definitions (/zh/docs/definitions)



## Aggregate Metrics [#aggregate-metrics]

### Unique Users [#unique-users]

The total number of distinct individuals who visited your website, identified by a unique user ID. Each user is counted only once regardless of how many times they visit.

### Sessions [#sessions]

A series of user interactions with your website within a given time frame. A session ends after 30 minutes of inactivity from the same user ID. Multiple pageviews can occur within one session.

### Pageviews [#pageviews]

The total number of times visitors have viewed pages on your website. Each time a page is loaded or reloaded counts as a pageview.

### Pages Per Session [#pages-per-session]

The average number of pages viewed during a session. Calculated by dividing the total number of pageviews by the total number of sessions.

### Bounce Rate [#bounce-rate]

The percentage of sessions where a user leaves your site after viewing only one page without any interaction. A high bounce rate might indicate that landing pages aren't relevant to visitors.

### Session Duration [#session-duration]

The average length of time users spend on your site during a session. Longer sessions typically indicate more engaged visitors.

## Individual Datapoints [#individual-datapoints]

### User ID [#user-id]

A unique identifier generated from a hash of the visitor's IP address and browser user-agent. This anonymized ID helps track unique visitors without storing personally identifiable information.

### Hostname [#hostname]

The domain name of the website being visited (e.g., example.com).

### Pathname [#pathname]

The path portion of the URL that follows the hostname (e.g., /blog/article).

### Entry Page [#entry-page]

The first page viewed by a user during a session. Identifies which pages commonly serve as entry points to your site.

### Exit Page [#exit-page]

The last page viewed by a user before ending their session. Helps identify where users tend to leave your site.

### Querystring [#querystring]

The portion of a URL that follows a question mark, containing parameters (e.g., ?utm\_source=newsletter).

### Page Title [#page-title]

The title of the webpage as defined in the HTML `<title>` tag.

### Referrer [#referrer]

The URL that a user was on before coming to your site. Shows how users are discovering your content.

### UTM Source [#utm-source]

Identifies which website, search engine, or other source is sending traffic to your site (e.g., google, newsletter, twitter).

### UTM Medium [#utm-medium]

Identifies the marketing medium (e.g., cpc, email, social).

### UTM Term [#utm-term]

Identifies paid search keywords. Used primarily for paid search campaigns.

### UTM Campaign [#utm-campaign]

Identifies the specific campaign or promotion that brought users to your site.

### UTM Content [#utm-content]

Identifies what specifically was clicked to bring the visitor to your site (e.g., banner ad, text link).

### Channel [#channel]

A categorization of traffic sources into standard groups such as direct, search, social, email, or referral.

### Browser [#browser]

The web browser used by the visitor (e.g., Chrome, Firefox, Safari).

### Browser Version [#browser-version]

The specific version of the browser being used.

### Operating System [#operating-system]

The operating system used by the visitor (e.g., Windows, macOS, iOS, Android).

### Operating System Version [#operating-system-version]

The specific version of the operating system being used.

### Language [#language]

The preferred language setting of the visitor's browser.

### Country [#country]

The country where the user is located, based on IP geolocation.

### Region [#region]

The state or region where the user is located, based on IP geolocation.

### City [#city]

The city where the user is located, based on IP geolocation.

### Latitude [#latitude]

The geographic latitude coordinate of the user's approximate location.

### Longitude [#longitude]

The geographic longitude coordinate of the user's approximate location.

### Screen Width [#screen-width]

The width of the visitor's screen or device viewport in pixels.

### Screen Height [#screen-height]

The height of the visitor's screen or device viewport in pixels.

### Device Type [#device-type]

The type of device being used (e.g., desktop, tablet, mobile).

### Event Name [#event-name]

The name of a custom event triggered by user interaction (e.g., "button\_click", "form\_submit").

### Event Properties [#event-properties]

Additional contextual data associated with custom events, stored as key-value pairs. Used to provide more detail about specific interactions.


# Embeds (/zh/docs/embed-widget)



Rybbit supports two iframe embed options:

* [Widget Embeds](/docs/embeds/widget) show a compact live visitor widget on any web page.
* [Dashboard Embed](/docs/embeds/dashboard) shows your analytics dashboard in an iframe.

Both embeds are self-contained iframes. There is no script tag, no JavaScript on your site, and no dependency on the Rybbit tracking script.

## Which Embed Should I Use? [#which-embed-should-i-use]

Use [Widget Embeds](/docs/embeds/widget) when you want a small live visitor count, chart, or top-countries summary. Widget Embeds do not make your dashboard public.

Use [Dashboard Embed](/docs/embeds/dashboard) when you want to publish the full read-only analytics dashboard. Dashboard Embed uses a generated private link, so Public Analytics is not required.


# Experiments (/zh/docs/experiments)





Experiments are A/B tests built on top of Rybbit. Each experiment splits your visitors across the variants of a [multivariate feature flag](/docs/feature-flags), then measures how often each variant completes a [conversion goal](/docs/goals). Rybbit calculates the conversion rate for every variant, the **lift** relative to your control, and how confident you can be that the difference is real.

<Callout type="info">
  An experiment ties together two features you may already use: a **multivariate feature flag** decides which variant each visitor sees, and a **goal** defines the conversion you are optimizing for. If you understand those two pieces, you understand experiments.
</Callout>

## How Experiments Work [#how-experiments-work]

An experiment has three moving parts:

| Part           | What it does                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assignment** | A multivariate feature flag assigns each visitor to one stable variant (for example `control` or `variant_a`) based on its rollout percentages.                                                   |
| **Exposure**   | When your code reads the flag with `rybbit.flag()`, Rybbit records an exposure for that variant. The number of distinct sessions exposed to a variant is the denominator for its conversion rate. |
| **Conversion** | The experiment's primary goal — a page visit or a custom event — counts as a conversion for whichever variant the visitor was assigned.                                                           |

Because assignment is sticky for a given visitor, a person sees the same variant on repeat visits, which keeps your results consistent.

## Creating an Experiment [#creating-an-experiment]

Open your site in the Rybbit dashboard, go to **Experiments**, and click **New experiment**. A guided wizard walks you through each step.

<Steps>
  <Step>
    ### Basics [#basics]

    Give the experiment a **name** and, optionally, a **hypothesis** and **description*&#x2A;. The hypothesis is internal context for your team — something like &#x2A;"Changing the CTA copy will increase signups."* It does not affect assignment or tracking.

    New experiments are created as **drafts** so you can add the implementation code before any traffic is split.
  </Step>

  <Step>
    ### Assignment [#assignment]

    Choose how visitors are split into variants:

    * **Create a new flag** — Define a new multivariate flag with its own variants and rollout split. Each variant needs a unique key, and the rollout percentages must add up to &#x2A;*100%**.
    * **Use an existing flag** — Pick a multivariate flag that is not already attached to another experiment.

    <Callout type="info">
      Each experiment uses its own multivariate flag. The flag's variant keys (such as `control` and `variant_a`) are what you branch on in code.
    </Callout>
  </Step>

  <Step>
    ### Goal [#goal]

    Pick the conversion you want to compare variants against:

    * **Create a new goal** — Define a **page goal** (a URL path such as `/signup/complete`) or an **event goal** (a custom event such as `signup_completed`). The form provides autocomplete suggestions based on paths and events already seen on your site.
    * **Use an existing goal** — Connect a goal you already track.
    * **Skip for now** — Create the experiment without a goal and add one later. Conversion results require a goal.
  </Step>

  <Step>
    ### Review and Implement [#review-and-implement]

    Review the assignment flag and goal, then create the experiment. Rybbit creates any new flag or goal you configured, connects them, and shows you the **implementation code** for the flag. The experiment stays in **draft** until you start it from the experiment list.
  </Step>
</Steps>

## Implementing in Code [#implementing-in-code]

Read the experiment's flag in your app and branch your UI or behavior on the returned variant. Reading the flag also records the exposure that powers your results, so make sure it runs wherever the tested experience is shown.

<Tabs items="['JavaScript', 'TypeScript']">
  <Tab value="JavaScript">
    ```javascript
    window.rybbit.onReady((rybbit) => {
      const variant = rybbit.flag("checkout_cta", "control");

      if (variant === "variant_a") {
        // Render the variant experience.
      } else {
        // Render the control experience.
      }
    });
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript
    type ExperimentVariant = "control" | "variant_a";

    window.rybbit.onReady((rybbit) => {
      const variant = rybbit.flag("checkout_cta", "control") as ExperimentVariant;

      switch (variant) {
        case "variant_a":
          // Render the variant experience.
          break;
        default:
          // Render the control experience.
          break;
      }
    });
    ```
  </Tab>
</Tabs>

If your primary goal is an **event goal**, fire that event when the conversion action happens:

```javascript
window.rybbit.onReady((rybbit) => {
  rybbit.event("signup_completed");
});
```

**Page goals** need no extra code — Rybbit counts sessions that reach the goal's path automatically.

<Callout type="info">
  Use a stable variant for the `rybbit.flag()` fallback (usually `"control"`) so visitors still get a sensible experience before the flag resolves or if the experiment is paused.
</Callout>

## Reading Results [#reading-results]

Each experiment shows a results panel comparing every variant. Results respect the global date range and filters applied on the page.

| Metric              | Description                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Variant**         | The variant key, with the **Control** marked as the baseline.                                                         |
| **Sessions**        | Sessions exposed to that variant, alongside the number that converted.                                                |
| **Conversion rate** | Conversions divided by the number of exposed sessions (the **Sessions** figure) for that variant.                     |
| **Lift**            | The percentage change in conversion rate relative to the control. Positive lift is shown in green, negative in red.   |
| **Confidence**      | How confident Rybbit is that the variant's difference from the control is real, based on a two-proportion comparison. |

Rybbit summarizes the state of each experiment at a glance:

* **Gathering data** — Not enough exposures or conversions yet to draw a conclusion.
* **Leading** — A variant is outperforming the control with at least **95% confidence**.
* **Winner** — The variant recorded as the winner once the experiment is decided.

<Callout type="warn">
  Avoid stopping an experiment the moment a variant looks ahead. Let it run until it reaches 95% confidence with a meaningful number of conversions, otherwise early noise can masquerade as a real difference.
</Callout>

## Experiment Lifecycle [#experiment-lifecycle]

Experiments move through four statuses, which you control from the experiment list:

| Status        | Meaning                                                                                 |
| ------------- | --------------------------------------------------------------------------------------- |
| **Draft**     | Created but not yet collecting results. Add your implementation code here.              |
| **Running**   | Actively splitting traffic and recording exposures and conversions.                     |
| **Paused**    | Temporarily stopped. Visitors keep their existing assignments.                          |
| **Completed** | Finished. Use this once you have a result and have shipped (or rolled back) the change. |

Use **Start**, **Pause**, and **Complete** on each experiment to move between states.

## Best Practices [#best-practices]

* Change one thing at a time so you can attribute any lift to a single difference.
* Make sure your variant rollout percentages add up to 100% unless you intentionally want unassigned traffic.
* Read the flag wherever the tested experience renders so every exposed visitor is counted.
* Pick a primary goal that directly reflects the outcome you care about, not a proxy metric.
* Wait for 95% confidence and a healthy sample size before declaring a winner.
* After completing an experiment, ship the winning variant and remove the flag branch to keep your code clean.

***

**Related Documentation:**

* [Feature Flags](/docs/feature-flags) — The assignment mechanism behind experiments
* [Goals](/docs/goals) — Define the conversion an experiment measures
* [Track Events](/docs/track-events) — Fire custom events for event goals
* [Tracking Script](/docs/script) — Load the script and use `onReady()`


# Feature Flags (/zh/docs/feature-flags)





Feature flags let you change product behavior without deploying new code. In Rybbit, a flag can be evaluated in the browser, on your server, or in both places. Flag assignments are also attached to analytics events so you can filter and compare behavior by flag value.

<Callout type="info">
  Feature flags are different from [tags](/docs/tagging). Tags label traffic that you already routed yourself. Feature flags decide which value a visitor receives at runtime.
</Callout>

## Create a Flag [#create-a-flag]

1. Open your site in the Rybbit dashboard.
2. Go to **Feature Flags**.
3. Click **New flag**.
4. Choose a stable **key**, such as `new_checkout` or `pricing_banner`.
5. Select the flag type, runtime, and targeting conditions.
6. Enable the flag when you are ready for it to evaluate as active.

The **key** is the public identifier used in code. Treat it as the flag name and avoid changing it after the flag is in use.

## Flag Types [#flag-types]

| Type                  | Returns                                         | Best for                                                                  |
| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
| **Boolean**           | `true` or `false`                               | Releasing a feature on/off, gradual rollouts, allowlists                  |
| **Multiple variants** | A variant key like `"control"` or `"variant_a"` | Comparing more than one experience or configuration                       |
| **Remote config**     | `true` plus a payload from `flagPayload()`      | Shipping structured config such as copy, colors, limits, or JSON settings |

### Boolean Flags [#boolean-flags]

Boolean flags support a rollout percentage for each condition set. If the visitor matches the condition set and falls inside the rollout bucket, `window.rybbit.flag()` returns `true`.

```javascript
window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);

  if (enabled) {
    showNewCheckout();
  }
});
```

### Multiple Variants [#multiple-variants]

Multiple variant flags return the selected variant key. Each variant has its own rollout percentage and optional payload.

```javascript
window.rybbit.onReady((rybbit) => {
  const variant = rybbit.flag("homepage_cta", "control");

  if (variant === "variant_a") {
    renderAlternateCTA();
  }
});
```

Variant rollout percentages are evaluated in order. If the visitor falls outside the total allocated percentage, the flag returns `false`.

### Remote Config [#remote-config]

Remote config flags are useful when you want Rybbit to choose a JSON payload. For remote config, `flag()` returns whether a config matched, and `flagPayload()` returns the actual config.

```javascript
window.rybbit.onReady((rybbit) => {
  const config = rybbit.flagPayload("checkout_config", {
    buttonText: "Continue",
    theme: "default",
  });

  renderCheckout(config);
});
```

Remote config can still use targeting. This lets you serve one config to beta users, another config to a country, and a default config to everyone else.

## Runtime [#runtime]

Each flag has a runtime:

| Runtime    | Evaluated by                 | Use when                                                       |
| ---------- | ---------------------------- | -------------------------------------------------------------- |
| **Client** | The browser tracking script  | UI changes, frontend copy, client-only experiments             |
| **Server** | Your backend through the API | Backend behavior, pricing logic, data access, anything private |
| **Both**   | Browser and server           | Both sides need the same decision                              |

<Callout type="warn">
  Do not put secrets in client or both-runtime flag payloads. Browser-evaluated flags and payloads are visible to the user.
</Callout>

## Targeting and Condition Sets [#targeting-and-condition-sets]

Flags use ordered condition sets. Each set contains targeting rules plus the rollout, variants, or payload for users who match that set.

Evaluation works like this:

1. Rybbit checks condition sets from top to bottom.
2. The first condition set whose rules all match is selected.
3. Rybbit applies the rollout, variant allocation, or remote config payload from that selected set.
4. Later condition sets are not evaluated.

This means condition set order matters. Put narrow segments first and broad defaults last.

<Callout type="warn">
  If a visitor matches a boolean condition set but falls outside that set's rollout percentage, Rybbit returns `false` and does not continue to later condition sets.
</Callout>

### Targeting Fields [#targeting-fields]

| Field           | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| Hostname        | Current hostname, such as `example.com`                          |
| Pathname        | Current path, such as `/pricing`                                 |
| Query parameter | A specific URL query parameter                                   |
| Referrer        | The document referrer                                            |
| Language        | Browser language, such as `en-US`                                |
| Country         | Visitor country resolved from IP                                 |
| Region          | Visitor region resolved from IP                                  |
| City            | Visitor city resolved from IP                                    |
| Device type     | Device category derived from user agent and screen size          |
| User ID         | The identified user ID, falling back to the anonymous visitor ID |
| User trait      | A trait set through `identify()` or `setTraits()`                |

### Operators [#operators]

Targeting rules support:

* `equals`
* `not_equals`
* `contains`
* `starts_with`
* `ends_with`
* `regex`

All rules in a condition set must match. Multiple condition sets act as ordered alternatives.

## Browser Runtime [#browser-runtime]

The tracking script automatically evaluates client and both-runtime flags when it loads. It sends context such as anonymous visitor ID, identified user ID, URL, referrer, language, screen size, IP-derived location, and saved user traits.

Use `onReady()` before reading flags if you need the evaluated value during page initialization:

```javascript
window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);
  const payload = rybbit.flagPayload("new_checkout", {});
});
```

Available browser methods:

<TypeTable
  type="{
  &#x22;flag(key, fallback)&#x22;: {
    description: &#x22;Returns a single flag value. Reading a flag also records a feature flag exposure event once per flag value/version.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flagPayload(key, fallback)&#x22;: {
    description: &#x22;Returns the payload for a flag or variant. Use this for remote config and multivariate payloads.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flags()&#x22;: {
    description: &#x22;Returns all evaluated flag values keyed by flag key.&#x22;,
    type: &#x22;function&#x22;,
  },
  &#x22;flagPayloads()&#x22;: {
    description: &#x22;Returns all available flag payloads keyed by flag key.&#x22;,
    type: &#x22;function&#x22;,
  },
}"
/>

Assignments are included on analytics events as a feature flag map. This lets you filter dashboard reports by flag key and value.

### Identify and Traits [#identify-and-traits]

If you call `identify()` or `setTraits()`, the browser runtime refreshes feature flags using the updated user context.

```javascript
window.rybbit.identify("user_123", {
  plan: "pro",
  beta: true,
});
```

You can then target flags using **User ID** or **User trait** rules.

## Server Runtime [#server-runtime]

Use server runtime for decisions that should not happen in the browser. The server endpoint returns server and both-runtime flags only.

```
POST /api/sites/:siteId/feature-flags/evaluate
```

### Request [#request]

<TypeTable
  type="{
  anonymousId: {
    description: &#x22;Stable anonymous visitor ID used for rollout bucketing. Keep this stable for sticky assignments.&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  identifiedUserId: {
    description: &#x22;Logged-in user ID. Enables user ID rules and loads saved user traits.&#x22;,
    type: &#x22;string&#x22;,
  },
  hostname: {
    description: &#x22;Hostname used by hostname targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  pathname: {
    description: &#x22;Path used by pathname targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  query: {
    description: &#x22;Parsed query parameter object used by query targeting rules.&#x22;,
    type: &#x22;Record<string, string>&#x22;,
  },
  querystring: {
    description: &#x22;Raw query string. Used if query is not provided.&#x22;,
    type: &#x22;string&#x22;,
  },
  referrer: {
    description: &#x22;Referrer used by referrer targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  language: {
    description: &#x22;Language code used by language targeting rules.&#x22;,
    type: &#x22;string&#x22;,
  },
  screenWidth: {
    description: &#x22;Screen width used with user agent parsing to derive device type.&#x22;,
    type: &#x22;number&#x22;,
  },
  screenHeight: {
    description: &#x22;Screen height used with user agent parsing to derive device type.&#x22;,
    type: &#x22;number&#x22;,
  },
}"
/>

<Tabs items="['cURL', 'JavaScript']">
  <Tab value="cURL">
    ```bash
    curl -X POST "https://app.rybbit.io/api/sites/123/feature-flags/evaluate" \
      -H "Authorization: Bearer rb_your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "anonymousId": "visitor_abc",
        "identifiedUserId": "user_123",
        "hostname": "example.com",
        "pathname": "/checkout",
        "query": { "plan": "pro" },
        "language": "en-US",
        "screenWidth": 1440,
        "screenHeight": 900
      }'
    ```
  </Tab>

  <Tab value="JavaScript">
    ```javascript
    const response = await fetch(
      "https://app.rybbit.io/api/sites/123/feature-flags/evaluate",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer rb_your_api_key_here",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          anonymousId: "visitor_abc",
          identifiedUserId: "user_123",
          hostname: "example.com",
          pathname: "/checkout",
          query: { plan: "pro" },
          language: "en-US",
          screenWidth: 1440,
          screenHeight: 900,
        }),
      }
    );

    const data = await response.json();
    const newCheckout = data.flags.new_checkout?.value === true;
    ```
  </Tab>
</Tabs>

### Response [#response]

```json
{
  "flags": {
    "new_checkout": {
      "key": "new_checkout",
      "value": true,
      "flagType": "boolean",
      "payload": { "copy": "Try it now" },
      "conditionSet": "Default",
      "version": 3,
      "reason": "rollout",
      "matched": true,
      "rolloutPercentage": 100
    }
  },
  "generatedAt": "2026-05-27T12:00:00.000Z"
}
```

Assignment fields:

| Field               | Description                                                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`             | The evaluated flag value. Boolean flags return `true` or `false`; multiple variant flags return a variant key or `false`; remote config returns `true` when matched. |
| `payload`           | Optional payload from the selected condition set or selected variant.                                                                                                |
| `variant`           | Selected variant key for multiple variant flags.                                                                                                                     |
| `conditionSet`      | Name of the condition set that matched.                                                                                                                              |
| `reason`            | Why the assignment was produced, such as `rollout`, `variant`, `remote_config`, `fallthrough`, `target_mismatch`, or `disabled`.                                     |
| `matched`           | Whether the flag produced an active match.                                                                                                                           |
| `rolloutPercentage` | The rollout percentage that was evaluated.                                                                                                                           |
| `version`           | Flag version. Increments when the flag is edited.                                                                                                                    |

## Analytics and Filtering [#analytics-and-filtering]

Feature flag assignments are stored on events. Browser-tracked events include evaluated client flags automatically. Server-side events can include a `feature_flags` object in the [HTTP API](/docs/api/sending-events) payload:

```json
{
  "site_id": "123",
  "type": "custom_event",
  "event_name": "purchase",
  "pathname": "/checkout",
  "feature_flags": {
    "new_checkout": "true",
    "homepage_cta": "variant_a"
  }
}
```

Use feature flag filters in the dashboard to compare behavior between flag values.

## Best Practices [#best-practices]

* Keep flag keys stable and descriptive, such as `new_checkout` or `pricing_page_copy`.
* Use **Client** runtime only for values that are safe to expose in the browser.
* Use **Server** runtime for permission checks, pricing logic, and private backend behavior.
* Put specific condition sets before broad default condition sets.
* Keep remote config payloads small and JSON-serializable.
* Use a stable `anonymousId` for server-side evaluation so rollout assignments remain sticky.
* Remove stale flags after rollout is complete to keep your dashboard and codebase clean.

**Related Documentation:**

* [Tracking Script](/docs/script)
* [Identify Users](/docs/identify-users)
* [Tagging](/docs/tagging)
* [API - Sending Events](/docs/api/sending-events)


# Filter traffic (/zh/docs/filter-traffic)





Rybbit provides server-side traffic filtering to keep unwanted data out of your analytics. You can exclude your own traffic, staging and preview environments, internal tools, monitoring checks, or entire countries.

Filters are configured from **Site Settings → Exclusions**.

## Available Filters [#available-filters]

| Filter                    | Use it for                                                            | Matching behavior                                         | Limit       |
| ------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- | ----------- |
| **IP Exclusions**         | Your home, office, VPN, or internal network traffic                   | Single IPs, CIDR ranges, and IPv4 ranges                  | 100 entries |
| **Country Exclusions**    | Regional filtering or compliance requirements                         | Two-letter ISO country codes, such as `US`, `GB`, or `DE` | 250 entries |
| **Path Exclusions**       | Admin pages, private pages, preview routes, or test pages             | Case-insensitive glob patterns using `*`                  | 100 entries |
| **Hostname Exclusions**   | Localhost, staging domains, preview deployments, or temporary domains | Case-insensitive glob patterns using `*`                  | 100 entries |
| **User Agent Exclusions** | Monitoring tools, headless browsers, or custom crawlers               | Case-insensitive substring matching                       | 100 entries |

When a request matches an exclusion, Rybbit returns a successful response but does not write the event to analytics storage.

## IP Exclusions [#ip-exclusions]

Block traffic from specific IP addresses or ranges at the server level. This is usually the best way to hide your own traffic.

Supported formats:

* **Single IPv4**: `192.168.1.1`
* **Single IPv6**: `2001:db8::1`
* **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`
* **IPv4 ranges**: `192.168.1.1-192.168.1.10`

For setup instructions and best practices, see [Hiding Your Own Traffic](/docs/hiding-own-traffic).

## Country Exclusions [#country-exclusions]

Block all traffic geolocated to specific countries. Rybbit resolves the visitor IP address with the MaxMind GeoLite2 database, then compares the resulting country code to your exclusion list.

Use two-letter ISO country codes:

* `US` for United States
* `GB` for United Kingdom
* `CN` for China
* `DE` for Germany

Country codes are stored as uppercase values in the dashboard and API.

<Callout type="warning">
  **Private IP addresses**: Country exclusion cannot work for private IP addresses such as `127.0.0.1`, `192.168.x.x`, `10.x.x.x`, or `172.16.x.x` because they cannot be geolocated. This includes localhost and Docker container IPs during local development.
</Callout>

<Callout type="info">
  **VPNs and proxies**: Visitors using VPNs or proxies are detected based on the VPN or proxy server location, not their physical location.
</Callout>

## Path Exclusions [#path-exclusions]

Exclude traffic to specific page paths. Path exclusions match the pathname only, not the query string.

Examples:

```txt
/admin/*
/preview
/internal/*
```

Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `/admin/*` matches `/admin/users` and `/admin/settings`.

Use path exclusions for pages that should not appear in analytics at all, such as admin dashboards, internal previews, or test routes.

<Callout type="info">
  For client-side-only pageview skipping, you can also use the tracking script's `data-skip-patterns` option. Site-level path exclusions are enforced on the server and also apply to session replay ingestion.
</Callout>

## Hostname Exclusions [#hostname-exclusions]

Exclude traffic from specific hostnames. This is useful when the same site ID is used across production, staging, preview, and local environments.

Examples:

```txt
localhost
staging.example.com
*.vercel.app
*.netlify.app
```

Matching is case-insensitive. A `*` wildcard matches any sequence of characters, so `*.vercel.app` matches `my-preview.vercel.app` but not `vercel.app`.

## User Agent Exclusions [#user-agent-exclusions]

Exclude traffic from requests whose user agent contains a configured substring.

Examples:

```txt
HeadlessChrome
MyMonitor
Pingdom
```

Matching is case-insensitive and uses substring matching, so `HeadlessChrome` matches `Mozilla/5.0 HeadlessChrome/120`.

Use user-agent exclusions for uptime monitors, synthetic checks, internal crawlers, or other tools with predictable user-agent strings.

## What Filters Apply To [#what-filters-apply-to]

Traffic filters run before normal analytics data is stored. They apply to:

* Pageviews
* Custom events
* Performance and Web Vitals events
* Error events
* Autocapture events
* Session replay batches

## How Filters Are Evaluated [#how-filters-are-evaluated]

Rybbit checks exclusions in this order:

1. IP address
2. Country
3. Path
4. Hostname
5. User agent

If any filter matches, the event is accepted with a `200` response but is not tracked. Changes usually take effect within 60 seconds because site configuration is cached briefly on the server.

## Testing Filters Locally [#testing-filters-locally]

To test country filtering locally, send a public IP through the `X-Real-IP` header:

```bash
curl -X POST http://localhost:3001/api/track \
  -H "Content-Type: application/json" \
  -H "X-Real-IP: 8.8.8.8" \
  -d '{
    "type": "pageview",
    "site_id": "your-site-id",
    "hostname": "example.com",
    "pathname": "/test"
  }'
```

For path and hostname filters, set `pathname` and `hostname` in the event payload to values that should match your configured exclusions.


# Funnels (/zh/docs/funnels)













<img alt="Funnels Dashboard" src="__img0" />

Funnels let you define a sequence of steps — page visits, custom events, or autocaptured interactions — and measure how many users progress through each stage. You can see where users convert, where they drop off, and drill into the sessions at each step to understand why.

## Creating a Funnel [#creating-a-funnel]

<img alt="Creating a Funnel" src="__img1" />

<Steps>
  <Step>
    ### Click "Create Funnel" [#click-create-funnel]

    Each funnel has:

    * **Name** — A label for the funnel (e.g., "Signup Flow", "Checkout Process")
    * **Steps** — Two or more sequential steps, each tracking a page visit, custom event, outbound link, button click, form submission, or copy event
  </Step>

  <Step>
    ### Add Steps [#add-steps]

    A funnel always must have at least two steps.

    There are six types of funnel steps. Path and custom event steps require a value. For the four autocaptured interaction types, the pattern is optional—leave it empty to match every interaction of that type.

    <Tabs items="['Path', 'Custom Event', 'Outbound Link', 'Button Click', 'Form Submit', 'Copy']">
      <Tab value="Path">
        Path steps match pageview events by URL path.

        * Enter a URL path starting with `/`
        * Wildcards are supported:
          * `*` matches a single path segment — `/products/*` matches `/products/shoes`
          * `**` matches multiple segments — `/docs/**` matches `/docs/api/v2/intro`
      </Tab>

      <Tab value="Custom Event">
        Custom event steps match events by name (e.g., `add_to_cart`, `purchase_completed`).

        Events must be tracked using the Rybbit tracking script. See [Track Events](/docs/track-events) for setup instructions.
      </Tab>

      <Tab value="Outbound Link">
        Outbound link steps match clicks on links that lead away from your site.

        * Enter a destination URL pattern such as `https://example.com/pricing` or `https://*.example.com/**`
        * Leave the pattern empty to match any outbound click

        Outbound link tracking is enabled by default.
      </Tab>

      <Tab value="Button Click">
        Button click steps match clicks on buttons, button/submit inputs, and elements with `role="button"`.

        * Enter a visible button-text pattern such as `Sign Up` or `Start * Trial`
        * Leave the pattern empty to match any button click

        Buttons that already use `data-rybbit-event` are recorded as custom events instead.
      </Tab>

      <Tab value="Form Submit">
        Form submit steps match submissions of HTML forms.

        * Enter a form name or ID pattern such as `signup-form`
        * The pattern can also match the form's action URL
        * Leave the pattern empty to match any form submission
      </Tab>

      <Tab value="Copy">
        Copy steps match text that visitors copy from your site.

        * Enter a copied-text pattern such as `PROMO*`
        * Leave the pattern empty to match any copied text
      </Tab>
    </Tabs>

    Autocaptured interaction patterns support wildcards: `*` matches one or more characters and `**` also matches an empty value. The form suggests values already observed on your site.

    <Callout type="info" title="Enable autocapture first">
      Button click, form interaction, and copy tracking are disabled by default. Enable the event types you want to use in the **Tracking** tab of your site settings. Only interactions collected after tracking is enabled can appear in a funnel. See [Autocapture](/docs/autocapture) for the properties collected with each type.
    </Callout>
  </Step>

  <Step>
    ### Configure Step Options (optional) [#configure-step-options-optional]

        <img alt="Step Options" src="__img2" />

    Each step has additional configuration options:

    * **Label** (optional) — A friendly display name for the step
    * **Hostname** (optional) — Restrict matching to a specific domain, useful for multi-domain sites
    * **Property Filters** (optional) — Filter by URL parameters (for path steps) or event properties (for all other step types). Multiple filters can be added per step, and all must match.
  </Step>
</Steps>

## Reading Funnel Results [#reading-funnel-results]

The funnel visualization updates in real time as you configure steps. For each step, you'll see:

* **Sessions** — How many sessions reached this step
* **Conversion Rate** — Percentage of the first step's sessions that reached this step
* **Dropped** — How many sessions completed the previous step but not this one
* **Dropoff Rate** — Percentage of the previous step's sessions lost at this point

The horizontal bar for each step shows two layers:

* **Solid bar** — Overall conversion from the first step
* **Striped overlay** — Conversion from the immediately previous step

Steps are evaluated sequentially — each step must occur after the previous one within the same session.

## Viewing Sessions [#viewing-sessions]

<img alt="Viewing Sessions" src="__img3" />

Click any step to expand it and view the sessions associated with that step:

* **Reached** tab — Sessions that completed this step
* **Dropped Off** tab — Sessions that reached the previous step but didn't make it to this one (available for step 2 and beyond)

Each session shows entry/exit pages, duration, location, device info, referrer, UTM parameters, and user ID if identified. Sessions are paginated.

***

**Related Documentation:**

* [Autocapture](/docs/autocapture) — Configure automatically captured interactions
* [Goals](/docs/goals) — Track single-action conversions
* [Track Events](/docs/track-events) — Set up custom event tracking


# Goals (/zh/docs/goals)













<img alt="Goals Dashboard" src="__img0" />

Goals let you define specific actions — from visiting a page to clicking a button — and measure how often your visitors complete them. Each goal tracks a conversion rate against total sessions, giving you a clear picture of how effectively your site drives key outcomes.

## Creating a Goal [#creating-a-goal]

<img alt="Creating a Goal" src="__img1" />

<Steps>
  <Step>
    ### Click "Create Goal" [#click-create-goal]

    Every goal has:

    * **Name** (optional) — A friendly label like "Completed Checkout" or "Signed Up"
    * **Type** — Page, custom event, outbound link, button click, form submission, or copied text
    * **Value** — A required path or custom event name, or an optional pattern that narrows an autocaptured interaction
  </Step>

  <Step>
    ### Choose a Goal Type [#choose-a-goal-type]

    There are six goal types. Page and custom event goals require a value. For the four autocaptured interaction types, the pattern is optional—leave it empty to count every interaction of that type.

    <Tabs items="['Page', 'Custom Event', 'Outbound Link', 'Button Click', 'Form Submit', 'Copy']">
      <Tab value="Page">
        Page goals track when a user visits a URL matching a given path pattern.

        * The value must be a path starting with `/` (not a full URL)
        * Wildcards are supported:
          * `*` matches a single path segment — `/blog/*` matches `/blog/my-post`
          * `**` matches multiple segments — `/docs/**` matches `/docs/api/v2/intro`

        The form provides autocomplete suggestions based on actual paths seen on your site.
      </Tab>

      <Tab value="Custom Event">
        Custom event goals track when an event with a specific name is fired. The value is the event name (e.g., `signup_clicked`, `purchase_completed`).

        Events must be tracked using the Rybbit tracking script. See [Track Events](/docs/track-events) for setup instructions.
      </Tab>

      <Tab value="Outbound Link">
        Outbound link goals track clicks on links that lead away from your site.

        * Enter a destination URL pattern such as `https://example.com/pricing` or `https://*.example.com/**`
        * Leave the pattern empty to count clicks to any external URL

        Outbound link tracking is enabled by default.
      </Tab>

      <Tab value="Button Click">
        Button click goals track clicks on buttons, button/submit inputs, and elements with `role="button"`.

        * Enter a visible button-text pattern such as `Sign Up` or `Start * Trial`
        * Leave the pattern empty to count any button click

        Buttons that already use `data-rybbit-event` are recorded as custom events instead.
      </Tab>

      <Tab value="Form Submit">
        Form submit goals track submissions of HTML forms.

        * Enter a form name or ID pattern such as `signup-form`
        * The pattern can also match the form's action URL
        * Leave the pattern empty to count any form submission
      </Tab>

      <Tab value="Copy">
        Copy goals track text that visitors copy from your site.

        * Enter a copied-text pattern such as `PROMO*`
        * Leave the pattern empty to count any copied text
      </Tab>
    </Tabs>

    Autocaptured interaction patterns support wildcards: `*` matches one or more characters and `**` also matches an empty value. The form suggests values already observed on your site.

    <Callout type="info" title="Enable autocapture first">
      Button click, form interaction, and copy tracking are disabled by default. Enable the event types you want to use in the **Tracking** tab of your site settings. Only interactions collected after tracking is enabled can count toward a goal. See [Autocapture](/docs/autocapture) for the properties collected with each type.
    </Callout>
  </Step>

  <Step>
    ### Add Property Filters (optional) [#add-property-filters-optional]

        <img alt="Property Filters" src="__img2" />

    You can narrow a goal to only count conversions when specific properties match:

    * **Page goals** — Filter by URL parameters (e.g., only count visits where `utm_source=adwords`)
    * **Custom event goals** — Filter by event properties (e.g., only count events where `plan=premium`)
    * **Autocaptured interaction goals** — Filter by captured properties such as `url`, `text`, `formName`, `formId`, or `formAction`

    Toggle **Match specific URL parameters** or **Match specific event properties** to add filters. You can add multiple filters per goal — all filters must match for a session to count as a conversion.
  </Step>
</Steps>

## Goal Metrics [#goal-metrics]

Each goal card displays:

* **Total Conversions** — The number of distinct sessions that completed the goal
* **Conversion Rate** — Conversions divided by total sessions in the selected time period, shown as a percentage with a visual progress bar

Goals respect the global date range and filters (country, device, browser, etc.) applied on the page.

## Viewing Converted Sessions [#viewing-converted-sessions]

<img alt="Viewing Converted Sessions" src="__img3" />

Click a goal card to expand it and see the sessions that converted. Each session shows:

* Entry and exit pages
* Session duration
* Location (country, region, city)
* Device, browser, and OS
* Referrer, channel, and UTM parameters
* User ID (if identified)

Sessions are sorted by most recent first and paginated.

***

**Related Documentation:**

* [Autocapture](/docs/autocapture) — Configure automatically captured interactions
* [Track Events](/docs/track-events) — Set up custom event tracking
* [Funnels](/docs/funnels) — Analyze multi-step conversion paths


# Hiding your own traffic (/zh/docs/hiding-own-traffic)





There are several ways to disable Rybbit tracking to hide your own visits from analytics.

<Tabs items="['IP Exclusion', 'Browser Extensions', 'localStorage Method']">
  <Tab>
    **IP Exclusion (Recommended)**: Block traffic from specific IP addresses or ranges at the server level for complete accuracy.

    ### Setting Up IP Exclusion [#setting-up-ip-exclusion]

    1. **Navigate to Site Settings**: Go to your site's settings page in the Rybbit dashboard
    2. **Find IP Exclusions section**: Scroll down to the "IP Exclusions" configuration
    3. **Add your IP addresses**: Enter the IP addresses or ranges you want to exclude

    ### Supported IP Formats [#supported-ip-formats]

    Rybbit supports multiple IP exclusion formats:

    * **Single IPv4**: `192.168.1.1`
    * **Single IPv6**: `2001:db8::1`, `::1`
    * **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`
    * **IPv4 ranges**: `192.168.1.1-192.168.1.10` (IPv4 only)

    ### Examples [#examples]

    ```
    # Your home IP address
    203.0.113.45

    # Your office network (CIDR)
    203.0.113.0/24

    # IP range for your team
    198.51.100.10-198.51.100.20

    # IPv6 address
    2001:db8::1
    ```

    ### Key Features [#key-features]

    * **Server-side filtering**: Traffic is blocked before it reaches your analytics, providing highly accurate exclusion
    * **Multiple formats**: Supports individual IPs, CIDR notation, and ranges
    * **IPv4 and IPv6**: Full support for both IP versions
    * **Near real-time updates**: Changes take effect within seconds
    * **No browser dependency**: Works regardless of browser or device

    <Callout type="info">
      **IP Stability Note**: IP addresses can change due to factors like mobile networks, VPN usage, ISP changes, and IPv6 privacy extensions. You may need to periodically update your excluded IPs to maintain effective filtering.
    </Callout>

    <Callout type="info">
      **Dynamic IP Addresses**: If you frequently use VPNs, mobile networks, or have a dynamic IP address that changes regularly, consider these approaches:

      * Use CIDR ranges that cover your typical IP pool (consult your ISP or VPN provider)
      * Combine IP exclusion with browser extensions for comprehensive coverage
      * Check your current IP periodically and update exclusions as needed
      * For corporate networks, exclude the entire office IP range rather than individual addresses
    </Callout>

    <Callout type="warning">
      **Note**: IPv6 range notation (e.g., `2001:db8::1-2001:db8::ff`) is not supported. Use CIDR notation instead (e.g., `2001:db8::/32`).
    </Callout>

    <Callout type="info">
      **Finding your IP**: You can find your current IP address by visiting sites like [whatismyipaddress.com](https://whatismyipaddress.com) or [ipinfo.io](https://ipinfo.io).
    </Callout>
  </Tab>

  <Tab>
    **Browser Extensions**: Easy client-side solution using community-maintained browser extensions.

    ### Available Extensions [#available-extensions]

    * **[Chrome Extension](https://chrome.google.com/webstore/detail/gofnfdfidbkpellionhpmkejgaajieoo)**: Install from the Chrome Web Store
    * **[Firefox Extension](https://addons.mozilla.org/en-US/firefox/addon/rybbit-opt-out/)**: Install from Firefox Add-ons

    These extensions automatically disable Rybbit tracking on all websites where you have Rybbit installed, without requiring any manual configuration.

    <Callout type="info">
      **Self-hosted users**: These extensions require Rybbit version 1.1.0 or higher. If you're running an older version, please update your installation or use the localStorage method.
    </Callout>

    *These extensions are community-maintained by [@davidfiala](https://github.com/davidfiala).*
  </Tab>

  <Tab>
    **localStorage Method**: Manual configuration using your browser's developer console for more granular control.

    <Steps>
      ### 1. Open your browser's developer console [#1-open-your-browsers-developer-console]

      Press **F12** or right-click the page and select "Inspect"

      Navigate to the "Console" tab

      ### 2. Disable tracking [#2-disable-tracking]

      Enter this command to disable tracking:

      ```js
      localStorage.setItem('disable-rybbit', 'true');
      ```

      ### 3. Re-enable tracking (when needed) [#3-re-enable-tracking-when-needed]

      If you want to re-enable tracking later, enter:

      ```js
      localStorage.removeItem('disable-rybbit');
      ```
    </Steps>
  </Tab>
</Tabs>

## Summary [#summary]

Multiple methods are available for hiding your own traffic, each with different advantages:

* **IP exclusion** provides the most accurate solution by blocking traffic at the server level, working regardless of browser or device
* **Browser extensions** offer convenience by automatically working across all your Rybbit-enabled websites
* **localStorage method** gives granular control for specific websites or temporary disabling

For most users, **IP exclusion is recommended** as it provides highly accurate filtering for all devices accessing your site from the excluded IP addresses. The other methods work at the browser level and may be useful for additional flexibility or temporary exclusions.


# Identify Users (/zh/docs/identify-users)





<Callout type="warn" title="GDPR & Privacy Compliance">
  User identification involves processing personal data. Before using these features, ensure you have a lawful basis for processing (typically user consent), have disclosed tracking in your privacy policy, and provide users the ability to access and delete their data. Only collect traits you have explicit consent to process.
</Callout>

Rybbit allows you to identify logged-in users and associate their activity with a persistent identity across devices and sessions. This enables powerful user-level analytics, including tracking user journeys, understanding retention, and personalizing experiences.

<img alt="identify users" src="__img0" />

## How It Works [#how-it-works]

By default, Rybbit assigns an anonymous ID to each visitor based on their device fingerprint. When you call `identify()`, you link this anonymous visitor to a known user ID, allowing you to:

* Track the same user across multiple devices
* Associate pre-login activity with the logged-in user
* Store user metadata (traits) like email, name, and custom fields
* View identified users in your dashboard with their real names

When a new alias is created (i.e., the first time `identify()` is called for a given device), Rybbit retroactively updates all past anonymous events from that device to include the identified user ID. This means pre-login pageviews and events are attributed to the user once they identify themselves.

## Special Trait Fields [#special-trait-fields]

When identifying users, certain trait fields are treated specially by Rybbit:

| Field      | Description                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| `username` | **Primary display name** - Shown in the users list and session cards instead of the user ID |
| `name`     | **Fallback display name** - Used if username is not provided                                |
| `email`    | Displayed below the user's name in the dashboard                                            |

You can also include any custom fields you need for segmentation and analysis.

## Limits [#limits]

* **Traits size**: Maximum 2KB per identify call. Traits are stored as JSON, so keep payloads concise.
* **User ID length**: Maximum 255 characters.

## API Reference [#api-reference]

### `window.rybbit.identify(userId, traits?)` [#windowrybbitidentifyuserid-traits]

Sets a custom user ID for tracking logged-in users across devices and sessions, with optional user traits (metadata).

* `userId` (String): The unique identifier for the user. This will be stored in localStorage and persist across browser sessions. &#x2A;*Note: Custom user IDs are stored exactly as provided without any hashing or modification.**
* `traits` (Object, Optional): An object containing user metadata like email, name, username, or any custom fields. This data is stored in Rybbit and can be used to identify users in the dashboard. Setting a trait to `null` removes it from the user's profile.

```javascript
// Identify a user when they log in (without traits)
window.rybbit.identify("user_12345");

// Identify a user with traits (recommended)
window.rybbit.identify("user_12345", {
  username: "johndoe",           // Primary display name
  name: "John Doe",              // Fallback display name
  email: "john@example.com",
  plan: "premium",
  company: "Acme Inc"
});

// All subsequent events and pageviews will be associated with this user ID
```

### `window.rybbit.setTraits(traits)` [#windowrybbitsettraitstraits]

Updates the traits for the currently identified user without re-identifying them. Useful for updating user properties after initial identification.

* `traits` (Object): An object containing user metadata. New traits are merged with existing traits. &#x2A;*Setting a trait to `null` removes it from the user's profile.**

```javascript
// Update user traits after they upgrade their plan
window.rybbit.setTraits({
  plan: "enterprise",
  upgraded_at: "2024-01-15"
});

// Remove a trait by setting it to null
window.rybbit.setTraits({
  temporary_flag: null  // This trait will be removed
});
```

**Note:** You must call `identify()` before using `setTraits()`. If no user is identified, this will log a warning.

### `window.rybbit.clearUserId()` [#windowrybbitclearuserid]

Clears the stored user ID. Useful when a user logs out.

```javascript
// Clear user identification when user logs out
window.rybbit.clearUserId();
```

### `window.rybbit.getUserId()` [#windowrybbitgetuserid]

Returns the currently set user ID, or `null` if none is set.

```javascript
// Check if a user is identified
const currentUserId = window.rybbit.getUserId();
if (currentUserId) {
  console.log('Current user:', currentUserId);
} else {
  console.log('No user identified');
}
```

## Important Notes [#important-notes]

* **Unique user counts**: Every user count in the dashboard — Unique Users, the users chart, the Users table, traits, and retention — keys on the custom user ID wherever one is present, falling back to the anonymous fingerprint only for visitors who have never identified. Two people sharing an IP address and browser count as two users, and one person on a laptop and a phone counts as one. Sites that never call `identify()` are unaffected. Because the count follows the IDs you pass, sending a fresh ID per visit (rather than a stable per-person ID) will inflate it.
* **Identified sessions**: When a custom user ID is present, session assignment includes both the anonymous device fingerprint and the custom user ID. Different identified users therefore remain in separate sessions even when they share the same IP address and user agent.
* **Shared devices**: If multiple users log in from the same device (same IP address and user agent), calling `identify()` with a new user ID updates the alias to point to the new user. Future events will be attributed to the most recently identified user. Past events that were already backfilled retain their original attribution.
* **Cross-device tracking**: Identifying the same user on different devices creates separate aliases. Events from each device are linked to the user independently via the `identified_user_id` field.
* **Retroactive backfill**: The backfill runs asynchronously when a new alias is first created. ClickHouse mutations may take a short time to propagate depending on table size. Subsequent `identify()` calls from the same device (even with a different user ID) do not re-backfill old events.
* **`clearUserId()` behavior**: Calling `clearUserId()` removes the user ID from localStorage so future events are anonymous. It does not delete the alias in the database or modify previously attributed events.

## Complete Example [#complete-example]

Here's a typical workflow for user identification:

```javascript
// When user logs in
function handleLogin(userData) {
  // Set user identification with traits
  window.rybbit.identify(userData.id, {
    username: userData.username,
    name: userData.fullName,
    email: userData.email,
    plan: userData.plan
  });

  // Track login event
  window.rybbit.event("User Login", {
    method: "email"
  });
}

// When user upgrades their plan
function handlePlanUpgrade(newPlan) {
  // Update traits without re-identifying
  window.rybbit.setTraits({
    plan: newPlan,
    upgraded_at: new Date().toISOString()
  });

  // Track upgrade event
  window.rybbit.event("Plan Upgraded", {
    new_plan: newPlan
  });
}

// When user logs out
function handleLogout() {
  // Track logout event
  window.rybbit.event("User Logout");

  // Clear user identification
  window.rybbit.clearUserId();
}

// Check identification status
function checkUserStatus() {
  const userId = window.rybbit.getUserId();
  if (userId) {
    console.log("User is identified:", userId);
  } else {
    console.log("Anonymous user");
  }
}
```

**Related Documentation:**

* [Track Events](/docs/track-events)
* [Behavior Analytics - Users Tab](/docs/behavior-analytics/users)
* [API - Sending Events](/docs/api/sending-events)


# Introduction (/zh/docs)



**Rybbit** is a powerful open source web and product analytics platform. Check out our [live demo](https://demo.rybbit.com/81) using a real production site.

<DocsHomeCards />

## Getting Started [#getting-started]

Choose the option that's right for you:

* **Cloud Version:** Sign up for the [hosted version](https://app.rybbit.io/signup). Get up and running in minutes.
* **Self-Host:** Follow our [self hosting guide](/docs/self-hosting) to set up Rybbit on your own server.

And then learn how to add the [tracking script](/docs/script) to your website to start collecting data.

## Code [#code]

Rybbit is open sourced under the AGPL-3.0 license. You can find the code on [GitHub](https://github.com/rybbit-io/rybbit).

## Community [#community]

Join our [Discord server](https://discord.gg/DEhGb4hYBj) or talk to me on [X](https://x.com/yang_frog). I'm always looking for feedback and ideas to make Rybbit as awesome as possible.


# Inviting users (/zh/docs/inviting-users)





<Callout type="info">
  On self-hosted instances, this workflow is slightly different. Instead of inviting users, you can create a new user and set their password directly since self-hosted instances don't send emails.
</Callout>

<Steps>
  <Step>
    ### Add the user to your organization [#add-the-user-to-your-organization]

    Go to **Settings > Organization** and click the "Invite Member" button. Enter the user's email address.
  </Step>

  <Step>
    ### Select the user's role [#select-the-users-role]

    You can assign the user one of three roles:

    **Owners** have full access to all features including billing, organization deletion, and member management.

    **Admins** can manage members and access all sites, but cannot delete the organization or manage billing.

    **Members** can view analytics for assigned sites only. They cannot manage settings or other members.

    #### Restricting site access for members [#restricting-site-access-for-members]

    When inviting a member, you can optionally restrict their access to specific sites. Check the "Restrict access to specific sites" option and select which sites the member should be able to view.

    If you don't enable this option, the member will have access to all sites in your organization.

    <Callout type="info">
      Site access restrictions only apply to members. Admins and owners always have full access to all sites.
    </Callout>
  </Step>

  <Step>
    ### Assign teams (optional) [#assign-teams-optional]

    If your organization has [teams](/docs/teams) set up, you can assign the new member to a team during the invitation. When the member accepts the invitation, they will automatically be added to the selected team.

    This is useful for ensuring new members immediately have access to the right group of sites without needing to configure access separately.
  </Step>

  <Step>
    ### Send the invite [#send-the-invite]

    Click the "Invite" button. The user will receive an email with a link to sign up for Rybbit. You can manage all pending invitations in the Organization settings page.
  </Step>
</Steps>

## Managing site access for existing members [#managing-site-access-for-existing-members]

You can change a member's site access at any time after they've joined your organization.

1. Go to **Settings > Organization**
2. Find the member in the list and click the edit (pencil) icon in the Actions column for that member
3. Toggle "Restrict access to specific sites" and select the sites they should have access to
4. Click "Save changes"

The member will immediately only see the sites you've selected. If you disable the restriction, they'll regain access to all sites.

<Callout type="info">
  Currently, each user can only be in one organization.
</Callout>


# Localhost tracking (/zh/docs/localhost-tracking)





Rybbit does not restrict tracking to your registered domain — the tracking script works from `localhost` (or any other origin) out of the box. As long as your snippet has a valid `data-site-id`, events sent during local development are recorded like any other traffic.

```html
<script
  defer
  src="https://app.rybbit.io/api/script.js"
  data-site-id="YOUR_SITE_ID">
</script>
```

<Callout type="warning">
  Because localhost traffic is tracked by default, the usual problem is the opposite one: development visits polluting your production analytics. Use one of the approaches below to keep your data clean.
</Callout>

## Keeping development traffic out of production data [#keeping-development-traffic-out-of-production-data]

### Option 1: Use a separate development site [#option-1-use-a-separate-development-site]

Create a second site in your Rybbit dashboard (e.g. "My App (dev)") and use its site ID during development. Your production site's data stays untouched, and you can still verify events end-to-end.

```jsx
// Next.js example
export function Analytics() {
  const siteId =
    process.env.NODE_ENV === 'development'
      ? process.env.NEXT_PUBLIC_RYBBIT_DEV_SITE_ID
      : process.env.NEXT_PUBLIC_RYBBIT_SITE_ID;

  return (
    <script
      defer
      src="https://app.rybbit.io/api/script.js"
      data-site-id={siteId}
    />
  );
}
```

### Option 2: Only load the script in production [#option-2-only-load-the-script-in-production]

If you don't need analytics while developing, skip loading the script entirely outside production:

```jsx
// Next.js example
export function Analytics() {
  if (process.env.NODE_ENV !== 'production') return null;

  return (
    <script
      defer
      src="https://app.rybbit.io/api/script.js"
      data-site-id={process.env.NEXT_PUBLIC_RYBBIT_SITE_ID}
    />
  );
}
```

```javascript
// Vanilla JS example
if (process.env.NODE_ENV === 'production') {
  const script = document.createElement('script');
  script.defer = true;
  script.src = 'https://app.rybbit.io/api/script.js';
  script.setAttribute('data-site-id', 'YOUR_SITE_ID');
  document.head.appendChild(script);
}
```

### Option 3: Filter the traffic instead [#option-3-filter-the-traffic-instead]

If you want the script loaded everywhere but excluded from your stats, use your site's exclusion settings — see [Filtering Traffic](/docs/filter-traffic) and [Hiding Your Own Traffic](/docs/hiding-own-traffic).

## Troubleshooting [#troubleshooting]

**Events not showing up from localhost?**

* Confirm `data-site-id` matches the site you're looking at in the dashboard
* Check the browser console for errors and the Network tab for `POST` requests to `/api/track`
* Disable ad blockers or privacy extensions — they commonly block analytics scripts on any origin, including localhost
* Make sure the page isn't excluded by your site's IP, path, or user-agent exclusion rules


# Managing your installation (/zh/docs/managing-your-installation)





## Helpful scripts [#helpful-scripts]

<Callout>
  You probably need to run `chmod +x *.sh` before running the scripts.
</Callout>

### Updating Your Installation [#updating-your-installation]

Rybbit is updated frequently with new features and bug fixes. You can update your installation by running the following commands:

**update.sh**: Update to the latest version by pulling new code and rebuilding containers

```bash
git pull
./update.sh
```

### Restarting Your Installation [#restarting-your-installation]

**restart.sh**: Restart all services (useful when you've changed .env settings)

```bash
./restart.sh
```

## Docker Compose Commands [#docker-compose-commands]

You can also manage services directly with Docker Compose:

* **Stop all services**:
  ```bash
  docker compose stop
  ```

* **Stop and remove containers** (preserves data):
  ```bash
  docker compose down
  ```

* **Start services** (if you used setup.sh with default webserver):
  ```bash
  docker compose --profile with-webserver up -d
  ```

* **Start services** (if you used setup.sh with --no-webserver):
  ```bash
  docker compose up -d
  ```

* **View logs**:
  ```bash
  docker compose logs -f
  ```

<Callout>
  If you are using your self-hosted Rybbit without anyone else, you can disable new user signups by setting `DISABLE_SIGNUP=true` in the `.env` file at the root of the repository.
</Callout>

## Database Access [#database-access]

You can access the databases by running the following commands:

* **Access Clickhouse**:
  ```bash
  docker exec -it clickhouse clickhouse-client --database analytics
  ```

* **Access Postgres**:
  ```bash
  docker exec -it postgres psql -U frog -d analytics
  ```

### Edit Session Replay Retention Policy [#edit-session-replay-retention-policy]

The default session replay retention policy is 30 days. This may be too long for some users as session replays can take up a lot of space. You can edit it by running the following command:

```bash
docker exec -it clickhouse clickhouse-client --database analytics
ALTER TABLE session_replay_events MODIFY TTL toDateTime(timestamp) + INTERVAL 14 DAY;
ALTER TABLE session_replay_metadata MODIFY TTL start_time + INTERVAL 14 DAY;
```

## Anonymous Usage Telemetry [#anonymous-usage-telemetry]

To help us improve Rybbit, self-hosted instances automatically send anonymous usage statistics to our cloud service. This includes:

* Number of rows in a few core ClickHouse tables (events and the session replay tables)
* Total database size
* Your Rybbit version
* A hashed instance identifier

No personal data, website content, or visitor information is ever collected.

<Callout type="info">
  You can completely disable telemetry by adding `DISABLE_TELEMETRY=true` to your `.env` file and restarting your services.
</Callout>


# Organization settings (/zh/docs/organization-settings)







Access organization settings by clicking on "Organization" or going to [app.rybbit.io/settings/organization](https://app.rybbit.io/settings/organization).

<img alt="organization settings" src="__img0" />

## Organization [#organization]

### Organization Name [#organization-name]

Update your organization's display name. Only the organization owner can change this setting.

### Delete Organization [#delete-organization]

Permanently delete the organization and all associated data including sites, analytics, reports, and member associations.

<Callout type="warn">
  This action cannot be undone. You must type the organization name to confirm deletion. If you have an active subscription, you must cancel it before deleting the organization.
</Callout>

## Members [#members]

View and manage all members in your organization. The members table shows:

* **Name** - Member's display name
* **Email** - Member's email address
* **Role** - Owner, Admin, or Member
* **Site Access** - Which sites the member can access
* **Joined** - When they joined the organization

### Member Roles [#member-roles]

| Role       | Permissions                                                                               |
| ---------- | ----------------------------------------------------------------------------------------- |
| **Owner**  | Full access to all features, can manage members, billing, and delete the organization     |
| **Admin**  | Can manage members and access all sites, cannot delete the organization or manage billing |
| **Member** | Can view analytics for assigned sites only, cannot manage settings or other members       |

### Inviting Members [#inviting-members]

Owners can invite new members or create user accounts. See the [Inviting Users](/docs/inviting-users) guide for detailed instructions.

### Teams [#teams]

You can organize sites into teams to control which members have access to which sites. See the [Teams](/docs/teams) guide for details.


# Roadmap (/zh/docs/roadmap)



Rybbit is a quickly growing project. We already have quite a few features, but there is much more to come.

## Planned features [#planned-features]

* Data import from Google Analytics, PostHog, and more
* More tracking script/SDK integration guides
* Custom themes

Once again, join our [Discord server](https://discord.gg/DEhGb4hYBj) or follow me on [X](https://x.com/yang_frog) to share your feedback and ideas. We would love to hear from you!


# Troubleshooting (/zh/docs/script-troubleshooting)





If you've installed the Rybbit tracking script but aren't seeing any traffic in your dashboard, this guide will help you diagnose and fix common issues.

## Check if the Script is Loaded [#check-if-the-script-is-loaded]

The first step is to verify that the Rybbit script is properly loaded on your page.

<Steps>
  <Step>
    ### Open Your Browser's Developer Console [#open-your-browsers-developer-console]

    Right-click anywhere on your webpage and select **Inspect** (or **Inspect Element**). Then click on the **Console** tab at the top of the panel that opens.

    Alternatively, you can use keyboard shortcuts:

    * **Windows/Linux**: Press `Ctrl + Shift + J` or `F12`
    * **Mac**: Press `Cmd + Option + J`
  </Step>

  <Step>
    ### Type "rybbit" and Press Enter [#type-rybbit-and-press-enter]

    In the console, type `rybbit` and press Enter.

    **If the script is loaded correctly**, you'll see an object with functions like this:

    ```javascript
    {event: ƒ, pageview: ƒ, identify: ƒ, setTraits: ƒ, clearUserId: ƒ, …}
    ```

    **If the script is NOT loaded**, you'll see an error like:

    ```
    Uncaught ReferenceError: rybbit is not defined
    ```

    If you see the error, the script is not loading properly. Continue reading for common causes.
  </Step>
</Steps>

## Common Issues [#common-issues]

### Data Attributes Being Stripped [#data-attributes-being-stripped]

Some platforms, content management systems, tag managers, and "delay JavaScript" optimizers automatically remove or sanitize `data-*` attributes from script tags, or rebuild the tag from a `data-src` placeholder and drop everything else. If your site ID was in a `data-site-id` attribute, it gets removed and the script logs `Please provide a valid site ID`.

**Platforms known to strip attributes:**

* Google Tag Manager
* WordPress optimization plugins with "delay JavaScript" enabled (WP Rocket, Perfmatters, FlyingPress, LiteSpeed Cache)
* Some WordPress page builders
* Certain website builders (Webflow, Wix, Squarespace in some configurations)
* Some CDN or caching plugins

**Solution:** Put the site ID in the script URL instead of a data attribute. Optimizers preserve the URL:

```html
<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
```

If your platform also rewrites the `src`, inject the script from JavaScript instead:

```javascript
<script>
  (function() {
    var el = document.createElement("script");
    el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
    el.defer = true;
    document.head.appendChild(el);
  })();
</script>
```

<Callout type="info">
  For detailed Google Tag Manager setup instructions, see our [Google Tag Manager Guide](/docs/guides/google-tag-manager).
</Callout>

### Ad Blockers [#ad-blockers]

In rare cases, ad blockers may block the Rybbit tracking script. While Rybbit is privacy-focused and doesn't use cookies for tracking, some aggressive ad blockers may still flag analytics scripts.

**How to check if an ad blocker is the issue:**

1. Temporarily disable your ad blocker
2. Refresh the page
3. Check the console again for the `rybbit` object

**Solutions:**

* **For your own testing**: Disable your ad blocker or add your site to the allowlist
* **For your visitors**: Consider setting up a [proxy](/docs/proxy-guide) to serve the script from your own domain, which significantly reduces the chance of being blocked

### Script Not in the Right Location [#script-not-in-the-right-location]

The Rybbit script should be placed in the `<head>` section of your HTML. If it's placed in the wrong location or loaded after the page has already finished loading, it may not work correctly.

**Verify the script placement:**

1. View your page source (right-click → **View Page Source**)
2. Search for `rybbit` or `script.js`
3. Confirm it appears within the `<head>...</head>` tags

### Incorrect Site ID [#incorrect-site-id]

Double-check that the `siteId` in your script URL (or your `data-site-id` attribute) matches the site ID shown in your Rybbit dashboard.

1. Go to your Rybbit dashboard
2. Navigate to your site's settings
3. Copy the site ID and compare it with what's in your script tag

### Content Security Policy (CSP) Blocking [#content-security-policy-csp-blocking]

If your site has a strict Content Security Policy, it may block the Rybbit script from loading or executing.

**Check for CSP errors:**

1. Open the browser console
2. Look for errors mentioning "Content Security Policy" or "CSP"

**Solution:** Add the Rybbit script domain to your CSP headers:

```
script-src 'self' https://app.rybbit.io;
connect-src 'self' https://app.rybbit.io;
```

If you're self-hosting Rybbit, replace `app.rybbit.io` with your Rybbit instance domain.

### Script Loading Too Late in SPAs [#script-loading-too-late-in-spas]

In single-page applications (React, Vue, Next.js, etc.), if the script loads after the initial page render, the automatic pageview might not fire.

**Solution:** Ensure the script is in your root HTML template (like `index.html` or `_document.js` in Next.js), not dynamically imported in a component.

For Next.js specifically, see our [Next.js Guide](/docs/guides/nextjs).

## Testing Your Installation [#testing-your-installation]

Once you've made changes, verify that tracking is working:

1. **Check the console**: Type `rybbit` to confirm the object exists
2. **Trigger a test event**: In the console, run:
   ```javascript
   rybbit.event("test_event")
   ```
3. **Check your dashboard**: Navigate to the Events tab in your Rybbit dashboard and look for "test\_event" (it may take a few seconds to appear)
4. **Check the Network tab**: In browser dev tools, go to the Network tab, filter by "track" or "rybbit", and verify requests are being sent with 200 status codes

## Still Having Issues? [#still-having-issues]

If you've tried all the above and are still not seeing traffic:

1. **Check the browser Network tab** for any failed requests to your Rybbit instance
2. **Verify your site ID** is correct in the dashboard
3. **Check if traffic is being filtered** - review your [IP exclusions](/docs/hiding-own-traffic) and [country exclusions](/docs/filter-traffic) to ensure your traffic isn't being blocked
4. **For self-hosted instances** - ensure your Rybbit server is running and accessible

***

**Related Documentation:**

* [Tracking Script Installation](/docs/script)
* [Track Events](/docs/track-events)
* [Proxy Guide](/docs/proxy-guide)
* [Google Tag Manager Guide](/docs/guides/google-tag-manager)
* [Hide Your Own Traffic](/docs/hiding-own-traffic)
* [Filter Traffic](/docs/filter-traffic)


# Tracking script (/zh/docs/script)





To start tracking user activity on your website, add the Rybbit tracking script to your site's HTML.

## Installation [#installation]

The webpage should give you this script tag like this when you first add a website. Place it within the `<head>` section of your website. Include it on every page you wish to track.

```html
<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" async></script>
```

If you are self-hosting Rybbit `app.rybbit.io` will be domain of your Rybbit instance.

The site ID is passed in the script URL. The older `data-site-id="YOUR_SITE_ID"` attribute still works, but the URL form is recommended because script optimizers (WP Rocket, Perfmatters, FlyingPress and similar "delay JavaScript" features) rebuild script tags and drop `data-*` attributes, while leaving the URL intact.

<Callout type="info">
  **Bypass Ad Blockers**: Some ad blockers may block analytics scripts regardless of privacy compliance. To improve tracking accuracy, you can proxy the tracking script through your own domain. See our [Proxy Guide](/docs/proxy-guide) for setup instructions for Next.js, Nginx, Caddy, and more.
</Callout>

## Configuration [#configuration]

### Site Settings Configuration [#site-settings-configuration]

Most tracking options are configured through your site settings in the Rybbit dashboard. The script automatically fetches these settings when it loads:

* **Automatic Initial Pageview**: Track the first pageview when the script loads
* **SPA Navigation**: Automatically track navigation in single-page applications
* **URL Parameters**: Include or exclude query strings from tracked URLs
* **Outbound Links**: Track clicks to external websites
* **Error Tracking**: Capture JavaScript errors and unhandled promise rejections
* **Session Replay**: Record user interactions for debugging and UX analysis
* **Web Vitals**: Collect Core Web Vitals performance metrics

### Script Attributes [#script-attributes]

These are the attributes you can pass to the script tag.

| Attribute            | Type     | Default | Description                                                                                                                                                                                                                                                                        |
| :------------------- | :------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-skip-patterns` | `string` | `[]`    | A JSON string array of URL path patterns to ignore. Pageviews matching these patterns won't be tracked. Supports two types of wildcards: `*` (matches within a segment) and `**` (matches across segments), plus regex patterns prefixed with `re:`.                               |
| `data-mask-patterns` | `string` | `[]`    | A JSON string array of URL path patterns to mask for privacy. Pageviews matching these patterns will be tracked, but the actual URL path will be replaced with the pattern itself in analytics data. Supports the same wildcards and `re:` regex patterns as `data-skip-patterns`. |
| `data-debounce`      | `string` | `"500"` | The delay (in milliseconds) before tracking a pageview after URL changes via the History API (`pushState`, `replaceState`). Set to `0` to disable debouncing.                                                                                                                      |
| `data-tag`           | `string` | `""`    | A label applied to all events from this script instance. Useful for A/B testing, deploy versioning, or cohort segmentation. Max 256 characters. See [Tagging](/docs/tagging).                                                                                                      |

{/* ### Feature Flags

  The tracking script automatically evaluates client and both-runtime feature flags when it loads. Read evaluated flags from `window.rybbit` after the script is ready:

  ```javascript
  window.rybbit.onReady((rybbit) => {
  const enabled = rybbit.flag("new_checkout", false);
  const config = rybbit.flagPayload("checkout_config", {});
  });
  ```

  Available methods:

  | Method | Description |
  | --- | --- |
  | `flag(key, fallback)` | Returns a boolean, variant key, or fallback value. Also records a feature flag exposure once per flag value/version. |
  | `flagPayload(key, fallback)` | Returns the payload for a flag, variant, or remote config. |
  | `flags()` | Returns all evaluated flag values. |
  | `flagPayloads()` | Returns all available flag payloads. |

  See [Feature Flags](/docs/feature-flags) for targeting rules, remote config, and server-side evaluation. */}

### Session Replay Attributes [#session-replay-attributes]

These attributes configure rrweb session replay behavior. They only apply when session replay is enabled in your site settings.

| Attribute                         | Type          | Default                          | Description                                                                                                                   |
| :-------------------------------- | :------------ | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `data-replay-mask-text-selectors` | `string`      | `[]`                             | A JSON string array of CSS selectors for elements whose text content should be masked. Example: `'[".user-name", "#email"]'`. |
| `data-replay-block-class`         | `string`      | `"rr-block"`                     | CSS class name for elements to exclude entirely from recording. Elements with this class won't appear in replays.             |
| `data-replay-block-selector`      | `string`      | `null`                           | CSS selector for elements to exclude from recording. Example: `".sensitive-content, #private-section"`.                       |
| `data-replay-ignore-class`        | `string`      | `"rr-ignore"`                    | CSS class name for elements whose input events should be ignored. The element appears but interactions aren't recorded.       |
| `data-replay-ignore-selector`     | `string`      | `null`                           | CSS selector for elements whose input events should be ignored. Example: `"input[name='credit-card']"`.                       |
| `data-replay-mask-text-class`     | `string`      | `"rr-mask"`                      | CSS class name for elements whose text content should be masked (shown as asterisks).                                         |
| `data-replay-mask-all-inputs`     | `boolean`     | `true`                           | When true, all input values are masked as asterisks for privacy. Set to `"false"` to disable.                                 |
| `data-replay-mask-input-options`  | `JSON object` | `{"password":true,"email":true}` | Specify which input types to mask. Example: `'{"password":true,"email":true,"tel":true}'`.                                    |
| `data-replay-collect-fonts`       | `boolean`     | `true`                           | When true, website fonts are collected for accurate replay rendering. Set to `"false"` to reduce data size.                   |
| `data-replay-sampling`            | `JSON object` | See below                        | Configure event sampling to reduce data volume. See sampling options below.                                                   |
| `data-replay-slim-dom-options`    | `JSON object` | See below                        | Configure which DOM elements to exclude from recording. See slimDOM options below.                                            |

### Pattern Matching Details [#pattern-matching-details]

For `data-skip-patterns` and `data-mask-patterns`, two types of wildcards are supported:

* `*` - Matches any characters within a single path segment (doesn't match across `/`)
* `**` - Matches any characters across multiple path segments (includes `/`)

Examples:

* `/admin/*` matches `/admin/dashboard` but not `/admin/users/list`
* `/admin/**` matches both `/admin/dashboard` and `/admin/users/list`
* `/blog/*/comments` matches `/blog/post-123/comments` but not `/blog/category/post/comments`

Regex patterns are also supported when prefixed with `re:`. The regex is used as-is, so add `^` and `$` if you want a full-path match.

Examples:

* `re:^/users/\\d+$` matches `/users/123` but not `/users/abc`
* `re:^/private/.*$` matches anything under `/private/`

Example usage:

```html
data-skip-patterns='["/admin/**", "/blog/drafts/*", "/preview/**"]'
data-mask-patterns='["/users/*/settings", "/accounts/**", "/orders/*/details"]'
```

Regex usage:

```html
data-skip-patterns='["re:^/private/.*$"]'
data-mask-patterns='["re:^/users/\\d+/settings$"]'
```

**Example with debugging overrides:**

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="456"
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-debounce="300"
></script>
```

## Session Replay Configuration [#session-replay-configuration]

When session replay is enabled in your site settings, you can fine-tune the recording behavior using the attributes above. This section covers the more complex configuration options.

### Privacy Controls [#privacy-controls]

Protect sensitive user information using these options:

| Option                 | Best For                                                           |
| ---------------------- | ------------------------------------------------------------------ |
| `data-replay-block-*`  | Completely hide elements (e.g., admin panels, modals with PII)     |
| `data-replay-ignore-*` | Show elements but don't record interactions (e.g., form fields)    |
| `data-replay-mask-*`   | Show element structure but hide text content (e.g., names, emails) |

**Example - Comprehensive privacy setup:**

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="123"
  data-replay-block-selector=".admin-panel, #payment-modal"
  data-replay-ignore-selector="input[name='ssn'], input[name='credit-card']"
  data-replay-mask-text-selectors='[".user-name", "#email", "[data-pii]"]'
  data-replay-mask-input-options='{"password":true,"email":true,"tel":true}'
></script>
```

### Sampling Configuration [#sampling-configuration]

The `data-replay-sampling` attribute controls how frequently events are recorded. Lower sampling rates reduce data volume but may miss some interactions.

**Default sampling configuration:**

```json
{
  "mousemove": false,
  "mouseInteraction": {
    "MouseUp": false,
    "MouseDown": false,
    "Click": true,
    "ContextMenu": false,
    "DblClick": true,
    "Focus": true,
    "Blur": true,
    "TouchStart": false,
    "TouchEnd": false
  },
  "scroll": 500,
  "input": "last",
  "media": 800
}
```

**Sampling options:**

* `mousemove`: `false` to disable, or number (ms) for sampling interval
* `scroll`: Sampling interval in milliseconds (e.g., `500` = sample every 500ms)
* `input`: `"last"` to only record final value, or `"all"` to record every keystroke
* `media`: Sampling interval for media events in milliseconds

**Example - Enable mouse tracking for UX analysis:**

```html
data-replay-sampling='{"mousemove":100,"scroll":150}'
```

### SlimDOM Options [#slimdom-options]

The `data-replay-slim-dom-options` attribute controls which DOM elements are excluded from recording to reduce data size.

**Default slimDOM configuration:**

```json
{
  "script": false,
  "comment": true,
  "headFavicon": true,
  "headWhitespace": true,
  "headMetaDescKeywords": true,
  "headMetaSocial": true,
  "headMetaRobots": true,
  "headMetaHttpEquiv": true,
  "headMetaAuthorship": true,
  "headMetaVerification": true
}
```

Set to `true` to enable all slimDOM options, or `false` to disable all:

```html
data-replay-slim-dom-options="true"
```

### Complete Example [#complete-example]

```html
<script
  src="https://app.rybbit.io/api/script.js"
  defer
  data-site-id="456"
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-debounce="300"
  data-replay-block-selector=".sensitive-content"
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-replay-mask-all-inputs="true"
  data-replay-collect-fonts="false"
  data-replay-sampling='{"mousemove":false,"scroll":500}'
></script>
```


# Segments (/zh/docs/segments)





A segment is a named, reusable set of [filters](/docs/feature-guides/main-tab#filters). Instead of rebuilding "mobile visitors from Germany who came from search" every time, save it once and apply it to the main dashboard, pages, sessions, funnels, journeys, retention, and exports with one click.

Segments live inside the **Filter** button. Nothing else changes in the dashboard: applying a segment expands its filters into the same filter bar every report already reads.

## Creating a segment [#creating-a-segment]

Open the **Filter** button and switch to the **Segments** tab. There are two ways to create one:

<Steps>
  <Step>
    ### From scratch [#from-scratch]

    Click **New segment**. The dialog has its own filter editor, so you can build the definition without applying anything to the dashboard first.
  </Step>

  <Step>
    ### From the current filters [#from-the-current-filters]

    Once the dashboard has filters applied, the Segments tab offers **Save current filters as segment**. The dialog opens with those filters and a suggested name.
  </Step>
</Steps>

Every segment has:

* **Name** — what the group means to you, such as "Paid traffic" or "Logged-in users"
* **Filters** — at least one. Every filter must match; multiple values inside one filter are alternatives
* **Available on** — this site only, or every site in the organization (organization-wide segments can only be created by admins and owners)
* **Description** — optional notes for your team
* **Show on the public dashboard and private links** — off by default

<Callout type="info">
  Filters in a segment are validated against the same schema as the filter bar, so a segment can never save something the dashboard could not query.
</Callout>

## Applying a segment [#applying-a-segment]

In the **Segments*&#x2A; tab, click a segment to apply it. It appears in the filter bar as a single chip named after the segment. Click the chip to see the filters it contains; click the &#x2A;*×** to remove all of them at once.

Ad-hoc filters work alongside an applied segment. Add a filter the usual way and it is ANDed with the segment. If one of the segment's own filters is changed on the dashboard, the chip reads &#x2A;*(edited)** so you know the row no longer matches the saved definition; the segment itself is unchanged.

Segments are part of the URL, so a dashboard link with a segment applied opens the same view for whoever you share it with.

## Editing and deleting [#editing-and-deleting]

Use the &#x2A;*⋯** menu on a segment in the Segments tab, or **Edit segment** from the applied chip. Changes apply everywhere the segment is used. Deleting a segment removes it for everyone; links that already expanded its filters keep working.

## Permissions [#permissions]

| Role                                    | Read and apply                                   | Create                     | Edit and delete       |
| --------------------------------------- | ------------------------------------------------ | -------------------------- | --------------------- |
| Owner or admin                          | All segments                                     | Site and organization-wide | Any segment           |
| Member                                  | All segments                                     | Site segments              | Segments they created |
| Public dashboard or private-link viewer | Segments marked as shown on the public dashboard | —                          | —                     |

## API and MCP [#api-and-mcp]

Every analytics endpoint accepts a `segment_id` query parameter that is expanded server-side, ANDed with any `filters` you also pass. Segments themselves are managed through the [Segments endpoints](/docs/api/segments/list). The [MCP server](/docs/mcp) exposes `list_segments` and `apply_segment`.


# Self-hosted vs Cloud (/zh/docs/self-host-vs-cloud)





Rybbit offers two deployment options: a fully-managed [cloud version](https://rybbit.com) and a [self-hosted](/docs/self-hosting) solution. This guide will help you choose the right option for your needs.

## Quick Comparison [#quick-comparison]

| Feature                               | Cloud                                                                                                                             | Self-Hosted                                                                                                                                          |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup Time**                        | Minutes                                                                                                                           | 30 - 120 minutes                                                                                                                                     |
| **Maintenance Required**              | None                                                                                                                              | Regular updates                                                                                                                                      |
| **Cookieless & Privacy friendly**     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Web Analytics**                     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **API**                               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Globe**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Session Replays**                   | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth="3" /> (On pro tier)</span> | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Funnels**                           | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Goals**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Sessions**                          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Journeys**                          | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Users**                             | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Retention**                         | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Error tracking**                    | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Organizations/Teams**               | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Pages View**                        | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />                                                                                    |
| **Web Vitals**                        | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                                   |
| **Email reports**                     | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <Minus className="w-5 h-5 inline" color="gray" strokeWidth="3" />                                                                                    |
| **Google Search Console integration** | <Check className="w-5 h-5 inline" color="green" strokeWidth="3" />                                                                | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth="3" /> (Requires Google OAuth env vars)</span> |


# Quick start (/zh/docs/self-hosting)





This guide will walk you through setting up your own instance of Rybbit using our setup script. If you want to manually setup Rybbit using the Docker Compose file, check out our [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) guide.

## Prerequisites [#prerequisites]

Before you begin, ensure you have the following:

* **A VPS:** Try to get one with at least 2GB of RAM.
* **A Domain Name:** You'll need a domain or subdomain (e.g., `tracking.yourdomain.com`) pointed to your VPS's IP address. HTTPS is required because browsers block tracking scripts served over insecure HTTP.

<Callout type="info">
  This guide has been tested on Ubuntu 24 LTS (x86\_64). If your server is ARM, it must be at least ARMv8.2-A for Clickhouse support.
</Callout>

## Setup Steps [#setup-steps]

<Steps>
  <Step>
    ### Point Your Domain to Your VPS [#point-your-domain-to-your-vps]

    Configure your domain's DNS settings to point to your VPS's public IP address. This usually involves:

    1. Finding your VPS's public IPv4 address (from your hosting provider, e.g., Hetzner).
    2. Logging into your domain registrar or DNS provider (e.g., GoDaddy, Namecheap, Cloudflare).
    3. Adding an `A` record:
       * **Host/Name:** Your desired subdomain (e.g., `tracking`) or `@` for the root domain.
       * **Value:** Your VPS's IPv4 address.
       * **Proxy Status:** When using Cloudflare, either:
         * Set to "DNS only" (recommended for most setups)
         * Or if keeping the proxy enabled, set SSL/TLS encryption mode to "Full" or "Full (strict)" in your Cloudflare dashboard under SSL/TLS settings

    <Callout type="warning">
      If you keep Cloudflare's proxy enabled and your domain has other services not running on HTTPS, using Full or Full (strict) mode might cause issues with those services. In such cases, either use "DNS only" mode or ensure all your services support HTTPS.
    </Callout>

    DNS changes might take some time to propagate globally. Use [DNS Checker](https://dnschecker.org/) to verify.
  </Step>

  <Step>
    ### Install Docker Engine [#install-docker-engine]

    Connect to your VPS via SSH.

    Follow the official Docker Engine installation instructions for your Linux distribution:
    [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
  </Step>

  <Step>
    ### Clone the Rybbit Repository [#clone-the-rybbit-repository]

    Clone the project repository from GitHub (Git is usually pre-installed on most server distributions):

    ```bash
    git clone https://github.com/rybbit-io/rybbit.git
    cd rybbit
    ```
  </Step>

  <Step>
    ### Run the Setup Script [#run-the-setup-script]

    The repository includes a setup script that configures the necessary environment variables (including generating a secure secret) and starts the application using Docker Compose.

    <Callout type="warning">
      Important: Make all scripts executable before proceeding!

      ```bash
      chmod +x *.sh
      ```
    </Callout>

    Run the setup script, replacing `your.domain.name` with the domain or subdomain you configured in the prerequisites:

    ```bash
    ./setup.sh your.domain.name
    ```

    If you want to enable 3D map visualizations, you can add the `--mapbox-token` flag:

    ```bash
    ./setup.sh your.domain.name --mapbox-token YOUR_MAPBOX_TOKEN
    ```

    The script will create a `.env` file and then build and start the containers. This might take a few minutes the first time.

    <Callout type="info">
      By default, we assume you are on a blank VPS and automatically setup a Caddy webserver. If you want to use your own webserver or need more control over the setup, check out:

      * [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) - For users with existing reverse proxies or deployment tools
      * [Advanced Self-Hosting Guide](/docs/self-hosting-guides/self-hosting-advanced) - For custom configurations and Nginx setup
    </Callout>
  </Step>

  <Step>
    ### Sign Up [#sign-up]

    Once the services are running and DNS has propagated, Caddy (the webserver) will automatically obtain an SSL certificate for your domain.

    Open your browser and navigate to `https://your.domain.name/signup` (using the domain you provided to the setup script).

    Create your admin account. You can then log in and start adding your websites!
  </Step>
</Steps>

If you run into any issues or need help, feel free to join our Discord community!


# Site settings (/zh/docs/site-settings)







Access your site settings by clicking the settings icon in your site's Rybbit dashboard.

<img alt="site settings" src="__img0" />

## Privacy & Security [#privacy--security]

### Public Analytics [#public-analytics]

Make your analytics publicly accessible by enabling the "Public Analytics" toggle.

* External viewers have read-only access to your analytics data
* Viewers cannot edit settings, reports, funnels, or goals
* Your other websites are not affected

### User ID Salting [#user-id-salting]

Rybbit stores user IDs as a hashed combination of IP + user agent. This allows identifying users across sessions, but may be considered storing personally identifiable data under GDPR.

Enable "User ID Salting" to have Rybbit forget about unique users every day. If a user visits 10 times in one day, they count as one user with 10 sessions. But if they visit once a day for 10 days, they appear as a new user each day.

**Downsides of enabling user ID salting:**

* User session history beyond 24 hours is not available
* Unique user counts over periods longer than 24 hours will be inflated
* The user retention page becomes effectively useless

### Block Bot Traffic [#block-bot-traffic]

Enable "Block Bot Traffic" to prevent detected bot traffic from being tracked in your normal analytics. See [Bot detection](/docs/bot-detection) for how Rybbit identifies and stores bot traffic.

### Track IP Address [#track-ip-address]

Enable "Track IP Address" to store the IP address of visitors.

<Callout type="warn">
  This is not GDPR compliant. Only enable if you have a legitimate need and proper consent mechanisms in place.
</Callout>

## Analytics Features [#analytics-features]

### Session Replay <span className="text-green-500 text-sm">(Pro)</span> [#session-replay-pro]

Record and replay user sessions to understand user behavior. This feature allows you to see exactly how users interact with your site.

### Web Vitals <span className="text-green-500 text-sm">(Standard)</span> [#web-vitals-standard]

Track Core Web Vitals metrics including:

* **LCP** (Largest Contentful Paint)
* **CLS** (Cumulative Layout Shift)
* **INP** (Interaction to Next Paint)
* **FCP** (First Contentful Paint)
* **TTFB** (Time to First Byte)

### Error Tracking <span className="text-green-500 text-sm">(Standard)</span> [#error-tracking-standard]

Capture JavaScript errors and exceptions from your site to identify and fix issues affecting your users.

### Track Outbound Links [#track-outbound-links]

Track when users click on external links leaving your site. Enabled by default.

### Track URL Parameters [#track-url-parameters]

Include query string parameters in page tracking. Enabled by default. Disable if you want cleaner URLs in your analytics or need to exclude sensitive parameters.

### Track Initial Page View [#track-initial-page-view]

Automatically track the first page view when the tracking script loads. Enabled by default.

### Track SPA Navigation [#track-spa-navigation]

Automatically track navigation in single-page applications (SPAs). Enabled by default. This detects URL changes via the History API and tracks them as page views.

## Traffic Filtering [#traffic-filtering]

### IP Exclusions [#ip-exclusions]

Block specific IP addresses or ranges from being tracked. Supports:

* Individual IP addresses (e.g., `192.168.1.1`)
* CIDR notation (e.g., `192.168.1.0/24`)
* IPv4 ranges (e.g., `192.168.1.1-192.168.1.255`)

### Country Exclusions [#country-exclusions]

Block all traffic from specific countries using ISO country codes (e.g., `US`, `DE`, `FR`).

### Path Exclusions [#path-exclusions]

Exclude traffic to specific pages. Use `*` as a wildcard (e.g., `/admin/*` or `/preview`). Matching is case-insensitive. Up to 100 path exclusions are allowed.

### Hostname Exclusions [#hostname-exclusions]

Exclude traffic from specific hostnames such as staging or preview domains. Use `*` as a wildcard (e.g., `localhost` or `*.vercel.app`). Matching is case-insensitive. Up to 100 hostname exclusions are allowed.

### User Agent Exclusions [#user-agent-exclusions]

Exclude traffic from user agents containing any of these terms. Matching is a case-insensitive substring (e.g., `HeadlessChrome`). Up to 100 user agent exclusions are allowed.

All of these exclusions work at the server level, ensuring blocked traffic never reaches your analytics database.

## Embeds [#embeds]

Show Rybbit data on another site with an embeddable iframe.

* **Widget Embeds** show a compact live visitor widget. Enable them from the **Widget Embeds** tab. This is independent of Public Analytics and only exposes the data the widget displays. See the [Widget Embeds guide](/docs/embeds/widget) for details.
* **Dashboard Embed** shows the analytics dashboard in an iframe. Configure it from the **Dashboard Embed** tab. It uses a generated private link, not Public Analytics. See the [Dashboard Embed guide](/docs/embeds/dashboard) for details.

## Google Search Console <span className="text-green-500 text-sm">(Cloud)</span> [#google-search-console-cloud]

Connect your Google Search Console account to see search performance data alongside your analytics.

## Change Domain [#change-domain]

Update the domain for your site. Changing domains does not affect existing data - all historical analytics are preserved.

## Delete Site [#delete-site]

Permanently delete a site and all associated data.

<Callout type="warn">
  This action cannot be undone. All analytics data, reports, funnels, and goals will be permanently deleted.
</Callout>


# Tagging (/zh/docs/tagging)



Tags let you label all events from a script instance with a string identifier. This is useful for A/B testing, deploy labeling, cohort segmentation, and any scenario where you want to slice your analytics by a custom dimension that applies to the entire page.

If you need Rybbit to choose a value at runtime, gradually roll out a feature, or serve remote config, use [Feature Flags](/docs/feature-flags) instead.

## How It Works [#how-it-works]

Add a `data-tag` attribute to your Rybbit script tag. Every event (pageviews, custom events, outbound clicks, etc.) sent from that page will include the tag value, which is stored in ClickHouse and available as a filter in the dashboard.

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="YOUR_SITE_ID"
  data-tag="variant-a"
></script>
```

The tag is a simple string with a maximum length of 256 characters. If `data-tag` is not set or is empty, no tag is stored.

## Use Cases [#use-cases]

### A/B Testing [#ab-testing]

Serve different script tags to different user groups and compare behavior:

```html
<!-- Variant A -->
<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-a"></script>

<!-- Variant B -->
<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-b"></script>
```

Then filter by tag in the dashboard to compare metrics between variants.

### Deploy / Release Labeling [#deploy--release-labeling]

Tag events with the current deploy version to correlate releases with changes in user behavior or errors:

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="1"
  data-tag="v2.4.1"
></script>
```

### Cohort Segmentation [#cohort-segmentation]

Label traffic from different sources, campaigns, or user segments:

```html
<script
  src="https://app.rybbit.io/api/script.js"
  async
  data-site-id="1"
  data-tag="beta-users"
></script>
```

## Filtering by Tag [#filtering-by-tag]

Once events with tags are flowing in, you can filter by tag anywhere in the dashboard:

1. Click the **filter** button in the dashboard header
2. Select **Tag** from the filter parameter dropdown
3. Choose an operator (is, is not, contains, etc.)
4. Enter the tag value

The tag filter works on all dashboard pages including overview, pages, referrers, events, users, funnels, and goals.

## API Usage [#api-usage]

When sending events via the [HTTP API](/docs/api/sending-events), include `tag` in the request body:

```json
{
  "site_id": "YOUR_SITE_ID",
  "type": "pageview",
  "hostname": "example.com",
  "pathname": "/",
  "tag": "variant-a"
}
```

## Important Notes [#important-notes]

* Each script instance can only have one tag. If you need multiple dimensions, consider using [custom event properties](/docs/track-events) instead.
* Tags are set at the script level, not per-event. All events from a page load share the same tag.
* The tag value is stored as-is (no hashing or transformation).
* Empty or missing `data-tag` attributes result in no tag being stored.

**Related Documentation:**

* [Tracking Script](/docs/script)
* [Track Events](/docs/track-events)
* [Identify Users](/docs/identify-users)


# Teams (/zh/docs/teams)







Teams let you group sites together and control which organization members can access them. This is useful for organizations managing multiple properties where different people are responsible for different sites.

Access teams by clicking on "Teams" or going to [app.rybbit.io/settings/teams](https://app.rybbit.io/settings/teams).

<img alt="teams" src="__img0" />

## How Teams Work [#how-teams-work]

A team has three things:

* **A name** — identifies the team (e.g. "Marketing Sites", "Client Projects")
* **Members** — organization members assigned to the team
* **Sites** — the sites that belong to the team

When a member is assigned to a team, they can access all sites within that team. Admins and owners always have access to all sites regardless of team assignments.

<Callout type="info">
  Teams are an organizational tool for admins and owners. Members with the "Member" role can only see sites that belong to their assigned teams (unless they have unrestricted access).
</Callout>

## Creating a Team [#creating-a-team]

1. Go to **Settings > Teams**
2. Click the **Create Team** button
3. Enter a team name
4. Select which members should belong to the team
5. Select which sites the team should have access to
6. Click **Create Team**

You can also create a team directly from the team filter on the home page.

## Managing Teams [#managing-teams]

### Editing a Team [#editing-a-team]

Click the edit icon on any team card to update its name, members, or site assignments.

### Deleting a Team [#deleting-a-team]

Click the delete icon on a team card. Sites assigned to the team will become unassigned and visible to all members.

<Callout type="warn">
  Deleting a team removes all member-to-site associations through that team. Members who only had access via the deleted team will lose access to those sites.
</Callout>

## Filtering by Team [#filtering-by-team]

On the home page, use the team selector in the toolbar to filter the site list by team. The options are:

* **All Teams** — show all sites
* **No Team** — show only sites not assigned to any team
* **Specific team** — show only sites belonging to that team

## Assigning Teams During Invitation [#assigning-teams-during-invitation]

When [inviting a new member](/docs/inviting-users), you can optionally assign them to a team. When the member accepts the invitation, they will automatically be added to the selected team.

## Permissions [#permissions]

| Role       | Can create teams | Can edit/delete teams | Can view team-restricted sites     |
| ---------- | ---------------- | --------------------- | ---------------------------------- |
| **Owner**  | Yes              | Yes                   | All sites                          |
| **Admin**  | Yes              | Yes                   | All sites                          |
| **Member** | No               | No                    | Only sites in their assigned teams |


# Track Events (/zh/docs/track-events)



The script exposes a global object `window.rybbit` with functions for manual tracking of events, as well as the ability to track events using data attributes on HTML elements.

## Using Data Attributes [#using-data-attributes]

You can track custom events by adding data attributes to any HTML element:

```html
<!-- Basic event tracking -->
<button data-rybbit-event="signup_clicked">Sign Up</button>

<!-- Event with custom properties -->
<button
  data-rybbit-event="purchase_click"
  data-rybbit-prop-product="premium"
  data-rybbit-prop-price="49.99"
>
  Buy Now
</button>
```

This approach requires no JavaScript and works on any clickable element.

## Available Functions [#available-functions]

### `window.rybbit.event(eventName, properties)` [#windowrybbiteventeventname-properties]

Tracks a custom event with optional properties.

* `eventName` (String): The name of the custom event (max 256 characters).
* `properties` (Object, Optional): An object containing custom data (max 2KB characters). Only strings numbers are supported as values.

```javascript
// Track a simple custom event
window.rybbit.event("Signup Button Clicked");

// Track a custom event with properties
window.rybbit.event("Item Added To Cart", {
  itemId: "PROD123",
  price: 49.99,
  category: "Clothing"
});
```

### `window.rybbit.pageview()` [#windowrybbitpageview]

Tracks a pageview. Useful when automatic SPA navigation tracking is disabled in your site settings, or when you need to manually trigger a pageview.

```javascript
// Track a pageview
window.rybbit.pageview();
```

## TypeScript Support [#typescript-support]

Put this as `rybbit.d.ts` anywhere in your project to avoid having to do `(window as any).rybbit.event()` everywhere.

```typescript
interface Rybbit {
    /**
     * Tracks a page view
     */
    pageview: () => void;

    /**
     * Tracks a custom event
     * @param name Name of the event
     * @param properties Optional properties for the event
     */
    event: (name: string, properties?: Record<string, any>) => void;

    /**
     * Sets a custom user ID for tracking logged-in users
     * @param userId The user ID to set (will be stored in localStorage)
     * @param traits Optional user metadata (email, name, custom fields)
     */
    identify: (userId: string, traits?: Record<string, unknown>) => void;

    /**
     * Updates traits for the currently identified user
     * @param traits User metadata to merge with existing traits
     */
    setTraits: (traits: Record<string, unknown>) => void;

    /**
     * Clears the stored user ID
     */
    clearUserId: () => void;

    /**
     * Gets the currently set user ID
     * @returns The current user ID or null if not set
     */
    getUserId: () => string | null;

    /**
     * Manually tracks outbound link clicks
     * @param url The URL of the outbound link
     * @param text Optional text content of the link
     * @param target Optional target attribute of the link
     */
    trackOutbound: (url: string, text?: string, target?: string) => void;

    /**
     * Evaluates a feature flag and returns its value. Reading a flag records a
     * feature flag exposure once per flag value/version.
     * @param key The flag key
     * @param fallback Value returned before flags resolve or if the flag is inactive
     */
    flag: <T = unknown>(key: string, fallback?: T) => T;

    /**
     * Returns the payload for a feature flag or its selected variant.
     * Use this for remote config and multivariate payloads.
     * @param key The flag key
     * @param fallback Value returned before flags resolve or if the flag is inactive
     */
    flagPayload: <T = unknown>(key: string, fallback?: T) => T;

    /**
     * Returns all evaluated flag values keyed by flag key
     */
    flags: () => Record<string, unknown>;

    /**
     * Returns all available flag payloads keyed by flag key
     */
    flagPayloads: () => Record<string, unknown>;

    /**
     * Runs a callback once the tracking script and feature flags are ready.
     * Use this before reading flags during page initialization.
     * @param callback Receives the ready rybbit instance
     */
    onReady: (callback: (rybbit: Rybbit) => void) => void;
}

declare global {
    interface Window {
        rybbit: Rybbit;
    }
}

export {};
```

## Server-Side Tracking [#server-side-tracking]

For tracking events from server-side applications, mobile apps, or any platform outside the browser, you can use the HTTP API. This is useful for:

* Server-side event tracking (Node.js, Python, Go, etc.)
* Mobile app analytics (iOS, Android, Flutter)
* Backend integrations and webhooks
* Scenarios where the JavaScript snippet can't be used

See the [API documentation](/docs/api/sending-events) for detailed examples in multiple languages including authentication, parameters, and rate limiting information.

***

**Related Documentation:**

* [Identify Users](/docs/identify-users)
* [Behavior Analytics - Events Tab](/docs/behavior-analytics/events)
* [Behavior Analytics - Users Tab](/docs/behavior-analytics/users)
* [Behavior Analytics - Sessions Tab](/docs/behavior-analytics/sessions)
* [Product Analytics - Retention Guide](/docs/product-analytics/retention_guide)
* [Product Analytics - Funnels](/docs/product-analytics/funnels_guide)
* [API - Sending Events](/docs/api/sending-events)
* [Blog: Churn Rate vs Retention Rate](/blog/churn-rate-vs-retention-rate)
* [Web SDK Reference](/docs/sdks/web)


# Troubleshooting (/zh/docs/troubleshooting)





## Full Docker Cleanup [#full-docker-cleanup]

If you encounter issues with Docker containers, images, or volumes and need to start fresh, you can perform a complete Docker cleanup. This will remove all containers, images, volumes, and custom networks.

<Callout type="warn">
  **Warning**: This will remove ALL Docker containers, images, and volumes on your system, not just Rybbit-related ones. Make sure you don't have other important Docker containers running.
</Callout>

### Steps for Complete Docker Cleanup [#steps-for-complete-docker-cleanup]

<Steps>
  <Step>
    ### Remove your environment file [#remove-your-environment-file]

    ```bash
    rm .env
    ```
  </Step>

  <Step>
    ### Stop all running containers: [#stop-all-running-containers]

    ```bash
    docker stop $(docker ps -q)
    ```
  </Step>

  <Step>
    ### Remove all containers (both running and stopped): [#remove-all-containers-both-running-and-stopped]

    ```bash
    docker rm -f $(docker ps -aq)
    ```
  </Step>

  <Step>
    ### Remove all images: [#remove-all-images]

    ```bash
    docker rmi -f $(docker images -q)
    ```
  </Step>

  <Step>
    ### Remove all volumes: [#remove-all-volumes]

    ```bash
    docker volume rm -f $(docker volume ls -q)
    ```
  </Step>

  <Step>
    ### Remove all custom networks (preserves default networks): [#remove-all-custom-networks-preserves-default-networks]

    ```bash
    docker network rm $(docker network ls | grep -v "bridge\|host\|none" | awk '{print $1}')
    ```
  </Step>
</Steps>

### Alternative: Rybbit-Specific Cleanup [#alternative-rybbit-specific-cleanup]

If you only want to clean up Rybbit-related Docker resources without affecting other containers, use these commands instead:

```bash
# Stop and remove Rybbit containers
docker-compose down

# Remove Rybbit images
docker-compose down --rmi all

# Remove Rybbit volumes (this will delete your data!)
docker-compose down --volumes

# Complete Rybbit cleanup
docker-compose down --rmi all --volumes --remove-orphans
```

### After Cleanup [#after-cleanup]

Once you've completed the cleanup, you can restart Rybbit by following the setup instructions:

```bash
# Copy environment file
cp .env.example .env

# Edit .env with your configuration
# Then start the services
docker-compose up -d
```

## ClickHouse keeps crashing on a Proxmox VM [#clickhouse-keeps-crashing-on-a-proxmox-vm]

ClickHouse requires the SSE 4.2 instruction set. Proxmox VMs default to a generic CPU type (like `kvm64` or `x86-64-v2-AES`) that doesn't expose all of the host CPU's instruction sets to the VM, which causes ClickHouse to fail with `Illegal instruction` errors or get stuck in a restart loop.

To fix this, set the VM's CPU type to `host` so it passes through the physical CPU directly:

<Steps>
  <Step>
    ### Open the VM's hardware settings [#open-the-vms-hardware-settings]

    In the Proxmox web UI, select your VM, then go to **Hardware** → **Processors** → **Edit**.
  </Step>

  <Step>
    ### Set the CPU type to `host` [#set-the-cpu-type-to-host]

    Change the **Type** dropdown to `host` and click **OK**.
  </Step>

  <Step>
    ### Fully stop and start the VM [#fully-stop-and-start-the-vm]

    A reboot from inside the guest is not enough — do a full **Stop** and then **Start** from Proxmox for the CPU change to take effect.
  </Step>
</Steps>

<Callout type="info">
  The `host` CPU type can prevent live migration between Proxmox nodes with different CPU models. If you need migration, any CPU type that includes SSE 4.2 (e.g. `x86-64-v2-AES` on a host that supports it, or newer) may also work — but `host` is the most reliable option.
</Callout>

## I ran out of disk space [#i-ran-out-of-disk-space]

Regular web analytics events take up almost no space in Clickhouse, so it is very unlikely that you ran out of disk space from from this. There are two main reasons why you might have run out of disk space:

### 1. You are using session replay [#1-you-are-using-session-replay]

On self-hosted instances where we don't have access to S3 compatible object storage, session replays are stored in Clickhouse. Each session replay is at least 1000x the data footprint of the web analytics events. So it's very easy to run out of disk space.

We have a 30 day retention policy for session replays events, so if you turn off session replay, your disk space will slowly come back. If you need to immediately free up space, you can truncate the session replays table:

```bash
docker exec -it clickhouse clickhouse-client --database analytics

TRUNCATE TABLE session_replay_events;
TRUNCATE TABLE session_replay_metadata;
```

### 2. You didn't mount the Clickhouse log suppression configs [#2-you-didnt-mount-the-clickhouse-log-suppression-configs]

In our [docker-compose.yml](https://github.com/rybbit-io/rybbit/blob/master/docker-compose.yml), we have a config for Clickhouse that suppresses logs. Clickhouse stores a ton of logs in the log tables by default. This will quickly fill up your disk space if left unchecked.

If you follow the standard installation process, the configs are already mounted for you. If you rolled your own Docker setup, you need to mount the configs manually.


# Migration to v1.0 (/zh/docs/v1-migration)





This guide covers the breaking changes and migration steps when upgrading to Rybbit v1.0.

## API Path Changes [#api-path-changes]

In v1.0, we've simplified the reverse proxy configuration by having the backend expect requests with the `/api/` prefix. This eliminates the need for custom path rewriting in reverse proxy configurations.

### If You're Using the Built-in Caddy Server [#if-youre-using-the-built-in-caddy-server]

**No action required.** The built-in Caddy server configuration has been automatically updated and will work without any changes on your part.

### If You're Using a Custom Reverse Proxy [#if-youre-using-a-custom-reverse-proxy]

**You need to remove any custom API path rewriting** from your reverse proxy configuration.

<Callout type="warn">
  **Important:** If you were using a custom reverse proxy (Nginx, Apache, etc.) with path rewriting rules for the `/api/` endpoint, you must remove these rules when upgrading to v1.0.
</Callout>

#### What to Remove [#what-to-remove]

Remove any configuration that strips or rewrites the `/api/` prefix when forwarding requests to the backend. Common examples include:

**Nginx - Remove these patterns:**

```nginx
# ❌ Remove this type of configuration
location /api/ {
    rewrite ^/api(/.*)$ $1 break;  # Remove this line
    proxy_pass http://localhost:3001/;  # Change trailing slash
}
```

**Update to:**

```nginx
# ✅ Correct v1.0 configuration
location /api/ {
    proxy_pass http://localhost:3001;  # No trailing slash, no rewrite
    proxy_set_header Host $host;
    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;
}
```

**Apache - Remove these patterns:**

```apache
# ❌ Remove this type of configuration
ProxyPass /api/ http://localhost:3001/
ProxyPassReverse /api/ http://localhost:3001/
```

**Update to:**

```apache
# ✅ Correct v1.0 configuration
ProxyPass /api/ http://localhost:3001/api/
ProxyPassReverse /api/ http://localhost:3001/api/
```

**Docker Compose with custom location rules:**

```yaml
# ❌ Remove rewrite rules like this
location /api/ {
    rewrite ^/api(/.*)$ $1 break;
    proxy_pass http://rybbit_backend:3001;
}
```

**Update to:**

```yaml
# ✅ Correct v1.0 configuration
location /api/ {
    proxy_pass http://rybbit_backend:3001;
}
```

#### Why This Change? [#why-this-change]

This change simplifies the reverse proxy setup and eliminates a common source of configuration errors. The backend now handles the `/api/` prefix internally, making the setup more straightforward and consistent across different proxy solutions.

## Migration Steps [#migration-steps]

1. **Backup your current configuration** before making any changes
2. **Update your reverse proxy configuration** to remove API path rewriting (if applicable)
3. **Update to v1.0** using the update script:
   ```bash
   ./update.sh
   ```
4. **Verify your setup** by checking that your Rybbit instance is accessible and functioning correctly

## Need Help? [#need-help]

If you encounter issues during migration or need assistance with your specific reverse proxy setup, feel free to join our Discord community for support.


# Compare Channel Performance (/zh/docs/api/channel-performance)





The channel that sends the most visitors is rarely the channel that sends the most *customers*. This guide ranks each acquisition channel by conversion rate so you can see which sources punch above their weight — and which ones are vanity traffic.

**Endpoints used:**

* [`GET /metric`](/docs/api/overview/metric) — sessions broken down by channel
* [`GET /goals`](/docs/api/goals/list) — conversion metrics, scoped with a channel filter

<Callout type="info">
  The key technique here is the [`filters` parameter](/docs/api/getting-started#filter-parameters). Almost every endpoint accepts it, so you can take any site-wide metric and recompute it for a single segment — here, one channel at a time.
</Callout>

## The workflow [#the-workflow]

<Steps>
  <Step>
    **List your channels** and their session counts with `metric?parameter=channel`.
  </Step>

  <Step>
    **For each channel, fetch your goal's conversion rate** by calling `/goals` with a `channel` filter applied.
  </Step>

  <Step>
    **Rank by conversion rate** to reveal which channels actually drive outcomes.
  </Step>
</Steps>

## Full script [#full-script]

This script ranks every channel by the conversion rate of a chosen goal (here, goal `1` — your signup goal). Swap in whichever goal matters to your business.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="channel-performance.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const PRIMARY_GOAL_ID = 1; // the goal you care about

    const range = { start_date: '2024-01-01', end_date: '2024-01-31', time_zone: 'America/New_York' };

    async function get(path, params) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    // 1. All channels with their session counts
    async function getChannels() {
      const { data } = await get('/metric', { parameter: 'channel', limit: 20, ...range });
      return data.data; // [{ value: 'Organic Search', count: 5400, ... }]
    }

    // 2. Conversion rate for one channel, scoped with a filter
    async function goalForChannel(channel) {
      const filters = JSON.stringify([{ parameter: 'channel', type: 'equals', value: [channel] }]);
      const { data } = await get('/goals', { filters, ...range });
      return data.find((g) => g.goalId === PRIMARY_GOAL_ID);
    }

    async function rankChannels() {
      const channels = await getChannels();

      const rows = await Promise.all(
        channels.map(async (c) => {
          const goal = await goalForChannel(c.value);
          return {
            channel: c.value || 'Direct',
            sessions: c.count,
            conversions: goal?.total_conversions ?? 0,
            // conversion_rate comes back as a 0–1 fraction
            conversionRate: (goal?.conversion_rate ?? 0) * 100,
          };
        })
      );

      return rows.sort((a, b) => b.conversionRate - a.conversionRate);
    }

    rankChannels().then((rows) => {
      console.log('Channel'.padEnd(18), 'Sessions'.padStart(10), 'Conv.'.padStart(8), 'Rate'.padStart(8));
      for (const r of rows) {
        console.log(
          r.channel.padEnd(18),
          r.sessions.toLocaleString().padStart(10),
          String(r.conversions).padStart(8),
          `${r.conversionRate.toFixed(2)}%`.padStart(8)
        );
      }
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python title="channel_performance.py"
    import os, json, requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    PRIMARY_GOAL_ID = 1  # the goal you care about

    RANGE = {"start_date": "2024-01-01", "end_date": "2024-01-31", "time_zone": "America/New_York"}

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def get(path, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def get_channels():
        # 1. All channels with their session counts
        return get("/metric", parameter="channel", limit=20, **RANGE)["data"]["data"]


    def goal_for_channel(channel):
        # 2. Conversion rate for one channel, scoped with a filter
        filters = json.dumps([{"parameter": "channel", "type": "equals", "value": [channel]}])
        goals = get("/goals", filters=filters, **RANGE)["data"]
        return next((g for g in goals if g["goalId"] == PRIMARY_GOAL_ID), None)


    def rank_channels():
        rows = []
        for c in get_channels():
            goal = goal_for_channel(c["value"])
            rows.append({
                "channel": c["value"] or "Direct",
                "sessions": c["count"],
                "conversions": goal["total_conversions"] if goal else 0,
                # conversion_rate comes back as a 0–1 fraction
                "conversion_rate": (goal["conversion_rate"] if goal else 0) * 100,
            })
        return sorted(rows, key=lambda r: r["conversion_rate"], reverse=True)


    print(f"{'Channel':<18}{'Sessions':>10}{'Conv.':>8}{'Rate':>8}")
    for r in rank_channels():
        print(f"{r['channel']:<18}{r['sessions']:>10,}{r['conversions']:>8}{r['conversion_rate']:>7.2f}%")
    ```
  </Tab>
</Tabs>

## Reading the result [#reading-the-result]

```text
Channel             Sessions   Conv.    Rate
Referral               1,820     310    17.03%
Organic Search         5,400     642    11.89%
Direct                 4,220     451    10.69%
Email                    980      88     8.98%
Paid Search            2,310     142     6.15%
Social                 6,150     119     1.93%
```

Social sends the **most** traffic (6,150 sessions) but converts the **worst** (1.93%). Referral sends a fraction of the volume but converts nine times better. The takeaway writes itself: the referral partnerships deserve more investment, and the social strategy needs a hard look before more budget goes into it.

<Callout type="warn">
  Conversion rate alone can mislead on tiny samples — Email looks healthy at 9% but it's only 88 conversions. Always show the raw `sessions` and `conversions` columns next to the rate so a channel with 12 sessions and one fluke conversion doesn't top your list.
</Callout>

## Variations [#variations]

* **By UTM campaign instead of channel:** swap `parameter: 'channel'` for `parameter: 'utm_campaign'`, and filter on `utm_campaign` in the goals call. Same code, campaign-level granularity.
* **Engagement instead of conversion:** call [`/overview`](/docs/api/overview/overview) with the channel filter to compare `bounce_rate` and `session_duration` per channel — useful when you don't have a goal defined yet.
* **Full-funnel by channel:** run [`/funnels/analyze`](/docs/api/funnels/analyze) with a channel filter to see *where* in the funnel each channel's visitors fall out, not just the final rate.

## Next steps [#next-steps]

* [Find Where Users Drop Off](/docs/api/funnel-dropoff) — once you know your best channels, fix the funnel they pour into.
* [Automated Weekly Report](/docs/api/weekly-report) — add a channel league table to a scheduled digest.


# Find Where Users Drop Off (/zh/docs/api/funnel-dropoff)





A funnel tells you *how many* people fall out at each step. The journeys endpoint tells you *where they went instead*. Putting them together turns "our signup funnel leaks at the pricing page" into "people leave the pricing page for the FAQ — they have unanswered questions."

**Endpoints used:**

* [`POST /funnels/analyze`](/docs/api/funnels/analyze) — step-by-step conversion and drop-off rates
* [`GET /journeys`](/docs/api/insights/journeys) — the most common navigation paths

## The workflow [#the-workflow]

<Steps>
  <Step>
    **Analyze the funnel** to get a drop-off rate for every step.
  </Step>

  <Step>
    **Find the worst step** — the one with the highest `dropoff_rate`.
  </Step>

  <Step>
    **Pull journeys that start at that step's page** using `stepFilters`, so you can see the most common next page for people who were there.
  </Step>
</Steps>

## Step 1 — Analyze the funnel [#step-1--analyze-the-funnel]

Define the path a converting user should take and post it to the analyze endpoint.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="Analyze the funnel"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;

    const range = { start_date: '2024-01-01', end_date: '2024-01-31', time_zone: 'America/New_York' };

    const funnelSteps = [
      { type: 'page',  value: '/',                 name: 'Homepage' },
      { type: 'page',  value: '/pricing',          name: 'Pricing' },
      { type: 'page',  value: '/signup',           name: 'Signup' },
      { type: 'event', value: 'signup_complete',   name: 'Complete' },
    ];

    async function analyzeFunnel() {
      const url = new URL(`${API}/api/sites/${SITE}/funnels/analyze`);
      Object.entries(range).forEach(([k, v]) => url.searchParams.set(k, v));

      const res = await fetch(url, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ steps: funnelSteps }),
      });
      const { data } = await res.json();
      return data; // array of { step_number, step_name, sessions, conversion_rate, dropoff_rate }
    }
    ```
  </Tab>

  <Tab value="Python">
    ```python title="Analyze the funnel"
    import os, requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]

    RANGE = {"start_date": "2024-01-01", "end_date": "2024-01-31", "time_zone": "America/New_York"}

    FUNNEL_STEPS = [
        {"type": "page",  "value": "/",               "name": "Homepage"},
        {"type": "page",  "value": "/pricing",        "name": "Pricing"},
        {"type": "page",  "value": "/signup",         "name": "Signup"},
        {"type": "event", "value": "signup_complete", "name": "Complete"},
    ]


    def analyze_funnel():
        res = requests.post(
            f"{API}/api/sites/{SITE}/funnels/analyze",
            params=RANGE,
            json={"steps": FUNNEL_STEPS},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        res.raise_for_status()
        return res.json()["data"]  # list of step results
    ```
  </Tab>
</Tabs>

A response looks like this — note that `dropoff_rate` is the percentage who left **between the previous step and this one**:

```json
{
  "data": [
    { "step_number": 1, "step_name": "Homepage", "sessions": 10000, "conversion_rate": 100,  "dropoff_rate": 0 },
    { "step_number": 2, "step_name": "Pricing",  "sessions": 4500,  "conversion_rate": 45,   "dropoff_rate": 55 },
    { "step_number": 3, "step_name": "Signup",   "sessions": 1800,  "conversion_rate": 18,   "dropoff_rate": 60 },
    { "step_number": 4, "step_name": "Complete", "sessions": 1080,  "conversion_rate": 10.8, "dropoff_rate": 40 }
  ]
}
```

## Step 2 — Find the worst step [#step-2--find-the-worst-step]

The leak isn't always the step with the fewest sessions — it's the step with the steepest **drop-off**. Pick the maximum `dropoff_rate`.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="Find the biggest leak"
    function biggestLeak(steps) {
      // Skip step 1 — it always has 0% drop-off
      return steps
        .filter((s) => s.step_number > 1)
        .reduce((worst, s) => (s.dropoff_rate > worst.dropoff_rate ? s : worst));
    }

    const steps = await analyzeFunnel();
    const leak = biggestLeak(steps);
    const enteredStep = steps[leak.step_number - 2]; // the step they were on before leaving

    console.log(
      `Worst leak: ${leak.dropoff_rate}% of users left after "${enteredStep.step_name}" ` +
      `instead of reaching "${leak.step_name}".`
    );
    ```
  </Tab>

  <Tab value="Python">
    ```python title="Find the biggest leak"
    def biggest_leak(steps):
        # Skip step 1 — it always has 0% drop-off
        return max((s for s in steps if s["step_number"] > 1), key=lambda s: s["dropoff_rate"])


    steps = analyze_funnel()
    leak = biggest_leak(steps)
    entered_step = steps[leak["step_number"] - 2]  # the step they were on before leaving

    print(
        f'Worst leak: {leak["dropoff_rate"]}% of users left after "{entered_step["step_name"]}" '
        f'instead of reaching "{leak["step_name"]}".'
    )
    ```
  </Tab>
</Tabs>

In the example above, the steepest drop-off is **60%, between Pricing and Signup** — of the 4,500 people who reached the pricing page, only 1,800 went on to signup. That makes the **pricing page** the one to investigate: it's where the audience was sitting right before the biggest leak.

## Step 3 — See where the leavers went [#step-3--see-where-the-leavers-went]

The [journeys endpoint](/docs/api/insights/journeys) ranks the most common page paths. Use `stepFilters` to anchor step `0` to the page people were dropping from — now every returned journey shows you a common *next* page for that audience.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="What did they do after the leaky page?"
    async function journeysFrom(page) {
      const stepFilters = JSON.stringify({ '0': page });
      const url = new URL(`${API}/api/sites/${SITE}/journeys`);
      url.searchParams.set('steps', '2');
      url.searchParams.set('limit', '10');
      url.searchParams.set('stepFilters', stepFilters);
      Object.entries(range).forEach(([k, v]) => url.searchParams.set(k, v));

      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      const { journeys } = await res.json();
      return journeys;
    }

    // The leaky step's page — '/pricing' in our example
    const leakyPage = funnelSteps[leak.step_number - 2].value;
    const journeys = await journeysFrom(leakyPage);

    console.log(`Where users go after ${leakyPage}:`);
    journeys
      .filter((j) => j.path[1] && j.path[1] !== '/signup') // exclude the intended next step
      .slice(0, 5)
      .forEach((j) => console.log(`  → ${j.path[1]}  (${j.count} sessions, ${j.percentage}%)`));
    ```
  </Tab>

  <Tab value="Python">
    ```python title="What did they do after the leaky page?"
    import json


    def journeys_from(page):
        res = requests.get(
            f"{API}/api/sites/{SITE}/journeys",
            params={"steps": 2, "limit": 10, "stepFilters": json.dumps({"0": page}), **RANGE},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        res.raise_for_status()
        return res.json()["journeys"]


    # The leaky step's page — '/pricing' in our example
    leaky_page = FUNNEL_STEPS[leak["step_number"] - 2]["value"]
    journeys = journeys_from(leaky_page)

    print(f"Where users go after {leaky_page}:")
    for j in [j for j in journeys if len(j["path"]) > 1 and j["path"][1] != "/signup"][:5]:
        print(f'  → {j["path"][1]}  ({j["count"]} sessions, {j["percentage"]}%)')
    ```
  </Tab>
</Tabs>

### The insight [#the-insight]

```text
Where users go after /pricing:
  → /faq          (1,240 sessions, 27.6%)
  → /             (820 sessions, 18.2%)
  → /enterprise   (610 sessions, 13.6%)
```

More than a quarter of people who hit Pricing and didn't sign up went to the FAQ — a strong signal that pricing raises questions your FAQ has to answer. That's a far more actionable finding than "the pricing page has a 60% drop-off."

<Callout type="info">
  **Quantify before you act.*&#x2A; Combine the funnel and journey numbers into a one-line business case: &#x2A;"2,700 users/month leave Pricing; 28% head to the FAQ. Surfacing the top FAQ answers on the pricing page could recover a meaningful share of them."*
</Callout>

## Next steps [#next-steps]

* [Compare Marketing Channel Performance](/docs/api/channel-performance) — find out which traffic sources fill the top of this funnel with people who actually convert.
* [Funnels API reference](/docs/api/funnels/analyze) — event steps, property matching, and per-step session lookups.


# Getting Started (/zh/docs/api/getting-started)





<Callout type="warn">
  The API is currently in beta. There may be breaking changes as we continue to improve and expand the API.
</Callout>

## API Playground [#api-playground]

The easiest way to explore and test the API is using the built-in **API Playground** in your Rybbit dashboard. Access it by navigating to any site and clicking "API Playground" in the sidebar.

The playground provides:

* **Endpoint browser** - Browse all available API endpoints
* **Parameter controls** - Configure request parameters with a visual interface
* **Exact time ranges** - Test date ranges with optional start and end times
* **Live responses** - See real API responses with your actual data
* **Code generation** - Copy ready-to-use code snippets

This is the recommended way to familiarize yourself with the API before integrating it into your applications.

## Guides [#guides]

Looking for what to *build* with the API? These end-to-end recipes chain endpoints together to solve a real problem:

* [**Automated Weekly Report**](/docs/api/weekly-report) — a scheduled digest of last week's traffic, week-over-week change, and top pages and sources.
* [**Find Where Users Drop Off**](/docs/api/funnel-dropoff) — locate the biggest leak in a funnel, then see where the people who abandon go instead.
* [**Compare Channel Performance**](/docs/api/channel-performance) — rank acquisition channels by how well they convert, not just how much traffic they send.
* [**Build a Live Visitor Feed**](/docs/api/live-feed) — poll the events endpoint for a real-time activity stream you can render or alert on.
* [**Export Events to a Warehouse**](/docs/api/export-events) — backfill your full event history and keep it in sync with an incremental job.

## Authentication [#authentication]

All API requests must include authentication using one of the following methods:

### Bearer Token (Recommended) [#bearer-token-recommended]

```bash
Authorization: Bearer your_api_key_here
```

### Query Parameter (Testing Only) [#query-parameter-testing-only]

```bash
?api_key=your_api_key_here
```

<Callout type="warn">
  Query parameters expose API keys in server logs and browser history. Use only for quick testing.
</Callout>

## Generating API Keys [#generating-api-keys]

Rybbit has two kinds of API keys:

* **Organization API keys** (recommended for integrations) — the organization's own credential. They can access every site in the organization and keep working when team members leave. Only organization admins and owners can create and manage them.
* **Personal API keys** — act as you, with exactly your access, including any site restrictions, across every organization you belong to. Best for personal scripts and for connecting MCP clients.

### Organization keys [#organization-keys]

1. Navigate to **Settings → Organization** in your Rybbit dashboard
2. Scroll to the **Organization API Keys** section (visible to admins and owners)
3. Enter a name for the key and click **Create**
4. Copy the key immediately (it won't be shown again)

### Personal keys [#personal-keys]

1. Navigate to **Settings → Account** in your Rybbit dashboard
2. Scroll to the **Personal API Keys** section
3. Enter a name for the key and click **Create**
4. Copy the key immediately (it won't be shown again)

Both kinds support restricting a key to specific permissions when you create it — leave restrictions off for a full-access key.

### Rate Limits (Cloud Only) [#rate-limits-cloud-only]

Requests are limited in two ways: a **burst** limit that is the same on every plan, and a **daily quota** that depends on your plan.

| Plan             | Burst                      | Daily quota             |
| ---------------- | -------------------------- | ----------------------- |
| **Free / Basic** | API keys not available     | —                       |
| **Standard**     | 50 requests per 10 seconds | 5,000 requests per day  |
| **Pro**          | 50 requests per 10 seconds | 25,000 requests per day |

The burst limit is a bucket of 50 requests that refills continuously at 5 requests per second. You can spend all 50 at once, then keep going at 5 per second — so short spikes are fine and there is no window boundary to line up with.

The daily quota resets at **00:00 UTC**.

Requests refused by the burst limit don't count against your daily quota.

#### Which budget a request is charged to [#which-budget-a-request-is-charged-to]

Limits apply per **credential owner**, never per key — creating more keys splits an existing budget rather than adding to it:

| Credential                       | Budget                                                                                      |
| -------------------------------- | ------------------------------------------------------------------------------------------- |
| **Organization key** (`rb_org_`) | The organization's. All of an organization's keys share it.                                 |
| **Personal key**                 | Yours. All of your personal keys share one budget, across every organization you belong to. |
| **OAuth token** (MCP)            | Yours, the same budget as your personal keys.                                               |

A personal key's quota follows the most generous plan among the organizations you belong to.

Self-hosted instances are not rate limited at all — neither tier applies, and no rate limit headers are sent.

#### Reading your remaining budget [#reading-your-remaining-budget]

Analytics and management endpoints report your current budget on every response, so you can pace a client without waiting to be rejected:

| Header                                      | Meaning                                        |
| ------------------------------------------- | ---------------------------------------------- |
| `X-RateLimit-Burst-Limit` / `-Remaining`    | Burst bucket size and tokens left              |
| `X-RateLimit-Burst-Reset`                   | Seconds until the bucket is full again         |
| `X-RateLimit-Daily-Limit` / `-Remaining`    | Daily quota and requests left today            |
| `X-RateLimit-Daily-Reset`                   | Seconds until 00:00 UTC                        |
| `RateLimit-Limit` / `-Remaining` / `-Reset` | Whichever of the two is closest to running out |

Treat these as advisory: a few endpoints resolve credentials outside the standard path and omit them. `Retry-After` on a `429` is always present.

#### When you hit a limit [#when-you-hit-a-limit]

A `429` names the limit you hit and tells you how long to wait, in seconds:

```json
{
  "error": "Rate limit exceeded",
  "scope": "daily",
  "limit": 5000,
  "retryAfter": 34200
}
```

`scope` is `burst` or `daily`, and the same value is in the `Retry-After` header. The difference matters: a `burst` rejection clears in about a second, while a `daily` one lasts until the quota resets. Back off accordingly rather than retrying straight away.

***

## Common Parameters [#common-parameters]

The following parameters are shared across all analytics endpoints.

### Time Parameters [#time-parameters]

All endpoints require date-based, exact datetime, or relative time parameters:

<TypeTable
  type="{
  start_date: {
    description: 'Start date for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD (e.g., &#x22;2024-01-15&#x22;)',
    required: false,
  },
  end_date: {
    description: 'End date for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD (e.g., &#x22;2024-01-31&#x22;)',
    required: false,
  },
  time_zone: {
    description: 'IANA timezone identifier',
    type: 'string',
    typeDescription: 'e.g., &#x22;America/New_York&#x22;, &#x22;Europe/London&#x22;, &#x22;Asia/Tokyo&#x22;. Required with date and exact datetime ranges.',
    required: false,
  },
  start_datetime: {
    description: 'Exact UTC start timestamp for the query period',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD HH:mm:ss (e.g., &#x22;2024-01-15 13:00:00&#x22;)',
    required: false,
  },
  end_datetime: {
    description: 'Exact UTC end timestamp for the query period. This boundary is exclusive.',
    type: 'string',
    typeDescription: 'Format: YYYY-MM-DD HH:mm:ss (e.g., &#x22;2024-01-15 15:00:00&#x22;)',
    required: false,
  },
  past_minutes_start: {
    description: 'Start of relative time range (older boundary)',
    type: 'number',
    typeDescription: 'Minutes ago from now. Must be greater than past_minutes_end.',
    required: false,
  },
  past_minutes_end: {
    description: 'End of relative time range (newer boundary)',
    type: 'number',
    typeDescription: 'Minutes ago from now. Must be less than past_minutes_start.',
    required: false,
  },
}"
/>

**Note:** You must provide either:

* All three date parameters (`start_date`, `end_date`, `time_zone`), OR
* All three exact datetime parameters (`start_datetime`, `end_datetime`, `time_zone`), OR
* Both relative parameters (`past_minutes_start`, `past_minutes_end`)

#### Examples [#examples]

**Date-based query (last 30 days):**

```
?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York
```

**Exact datetime query (8 AM to 10 AM in New York on Jan 15, sent as UTC):**

```
?start_datetime=2024-01-15%2013:00:00&end_datetime=2024-01-15%2015:00:00&time_zone=America/New_York
```

**Relative query (last 60 minutes):**

```
?past_minutes_start=60&past_minutes_end=0
```

### Filter Parameters [#filter-parameters]

The `filters` parameter accepts a JSON-encoded array of filter objects to narrow down your data.

You can also pass `segment_id`, the ID of a [saved segment](/docs/segments), instead of or alongside `filters`. The segment's filters are expanded on the server and ANDed with any `filters` you pass. Use the [Segments endpoints](/docs/api/segments/list) to find IDs. Public and private-link callers can only use segments marked as shown on the public dashboard.

```
?start_date=2024-01-01&end_date=2024-01-31&time_zone=UTC&segment_id=12
```

#### Filter Object Structure [#filter-object-structure]

<TypeTable
  type="{
  parameter: {
    description: 'The dimension to filter on',
    type: 'FilterParameter',
    typeDescription: 'See Filter Parameters table below',
    required: true,
  },
  type: {
    description: 'The type of comparison to perform',
    type: 'FilterType',
    typeDescription: '&#x22;equals&#x22; | &#x22;not_equals&#x22; | &#x22;contains&#x22; | &#x22;not_contains&#x22; | &#x22;regex&#x22; | &#x22;not_regex&#x22; | &#x22;greater_than&#x22; | &#x22;less_than&#x22;',
    required: true,
  },
  value: {
    description: 'Array of values to match against',
    type: 'Array<string | number>',
    typeDescription: 'Multiple values are treated as OR conditions',
    required: true,
  },
}"
/>

#### Filter Types [#filter-types]

<TypeTable
  type="{
  equals: {
    description: 'Exact match',
    type: 'string',
    typeDescription: 'Value must exactly match',
  },
  not_equals: {
    description: 'Exclude exact matches',
    type: 'string',
    typeDescription: 'Value must not match',
  },
  contains: {
    description: 'Substring match',
    type: 'string',
    typeDescription: 'Value must contain the substring (uses SQL LIKE %value%)',
  },
  not_contains: {
    description: 'Exclude substring matches',
    type: 'string',
    typeDescription: 'Value must not contain the substring',
  },
  regex: {
    description: 'Regular expression match',
    type: 'string',
    typeDescription: 'Value must match the regex pattern (max 500 characters)',
  },
  not_regex: {
    description: 'Exclude regex matches',
    type: 'string',
    typeDescription: 'Value must not match the regex pattern',
  },
  greater_than: {
    description: 'Numeric greater than',
    type: 'number',
    typeDescription: 'For numeric fields like lat, lon',
  },
  less_than: {
    description: 'Numeric less than',
    type: 'number',
    typeDescription: 'For numeric fields like lat, lon',
  },
}"
/>

#### Available Filter Parameters [#available-filter-parameters]

**Browser & Device**

<TypeTable
  type="{
  browser: {
    description: 'Browser name',
    type: 'string',
    typeDescription: 'e.g., &#x22;Chrome&#x22;, &#x22;Firefox&#x22;, &#x22;Safari&#x22;',
  },
  browser_version: {
    description: 'Browser with version',
    type: 'string',
    typeDescription: 'e.g., &#x22;Chrome 120&#x22;',
  },
  operating_system: {
    description: 'Operating system name',
    type: 'string',
    typeDescription: 'e.g., &#x22;Windows&#x22;, &#x22;macOS&#x22;, &#x22;Linux&#x22;',
  },
  operating_system_version: {
    description: 'OS with version',
    type: 'string',
    typeDescription: 'e.g., &#x22;Windows 10/11&#x22;, &#x22;macOS 14&#x22;',
  },
  device_type: {
    description: 'Device category',
    type: 'string',
    typeDescription: '&#x22;desktop&#x22;, &#x22;mobile&#x22;, &#x22;tablet&#x22;',
  },
  dimensions: {
    description: 'Screen dimensions',
    type: 'string',
    typeDescription: 'e.g., &#x22;1920x1080&#x22;, &#x22;390x844&#x22;',
  },
  language: {
    description: 'Browser language',
    type: 'string',
    typeDescription: 'e.g., &#x22;en-US&#x22;, &#x22;es-ES&#x22;',
  },
}"
/>

**Location**

<TypeTable
  type="{
  country: {
    description: 'Country code',
    type: 'string',
    typeDescription: 'ISO 3166-1 alpha-2 code, e.g., &#x22;US&#x22;, &#x22;GB&#x22;',
  },
  region: {
    description: 'Geographic region/state',
    type: 'string',
    typeDescription: 'e.g., &#x22;California&#x22;, &#x22;England&#x22;',
  },
  city: {
    description: 'City name with region prefix',
    type: 'string',
    typeDescription: 'Format: &#x22;Region-City&#x22;, e.g., &#x22;CA-San Francisco&#x22;',
  },
  timezone: {
    description: 'User timezone',
    type: 'string',
    typeDescription: 'IANA timezone, e.g., &#x22;America/New_York&#x22;',
  },
  lat: {
    description: 'Latitude',
    type: 'number',
    typeDescription: 'Supports greater_than, less_than, equals (with 0.001 tolerance)',
  },
  lon: {
    description: 'Longitude',
    type: 'number',
    typeDescription: 'Supports greater_than, less_than, equals (with 0.001 tolerance)',
  },
}"
/>

**Page & Traffic**

<TypeTable
  type="{
  pathname: {
    description: 'URL pathname',
    type: 'string',
    typeDescription: 'e.g., &#x22;/blog/post-title&#x22;',
  },
  page_title: {
    description: 'HTML page title',
    type: 'string',
  },
  hostname: {
    description: 'Website hostname',
    type: 'string',
    typeDescription: 'e.g., &#x22;example.com&#x22;',
  },
  querystring: {
    description: 'URL query string',
    type: 'string',
    typeDescription: 'e.g., &#x22;?ref=twitter&#x22;',
  },
  referrer: {
    description: 'Referrer domain (without www)',
    type: 'string',
    typeDescription: 'e.g., &#x22;google.com&#x22;, &#x22;twitter.com&#x22;',
  },
  entry_page: {
    description: 'First page in session (landing page)',
    type: 'string',
  },
  exit_page: {
    description: 'Last page in session',
    type: 'string',
  },
  channel: {
    description: 'Marketing channel',
    type: 'string',
    typeDescription: 'e.g., &#x22;Direct&#x22;, &#x22;Organic Search&#x22;, &#x22;Social&#x22;',
  },
}"
/>

**UTM Parameters**

<TypeTable
  type="{
  utm_source: {
    description: 'UTM source parameter',
    type: 'string',
    typeDescription: 'e.g., &#x22;google&#x22;, &#x22;newsletter&#x22;',
  },
  utm_medium: {
    description: 'UTM medium parameter',
    type: 'string',
    typeDescription: 'e.g., &#x22;cpc&#x22;, &#x22;email&#x22;',
  },
  utm_campaign: {
    description: 'UTM campaign parameter',
    type: 'string',
  },
  utm_term: {
    description: 'UTM term parameter',
    type: 'string',
  },
  utm_content: {
    description: 'UTM content parameter',
    type: 'string',
  },
}"
/>

**User & Events**

<TypeTable
  type="{
  user_id: {
    description: 'User identifier',
    type: 'string',
    typeDescription: 'Matches both device fingerprint and custom identified user ID',
  },
  event_name: {
    description: 'Custom event name',
    type: 'string',
    typeDescription: 'Filters to sessions containing the event',
  },
}"
/>

#### Filter Examples [#filter-examples]

<Tabs items="['Single Filter', 'Multiple Filters', 'Contains', 'Regex', 'Numeric', 'URL-encoded']">
  <Tab value="Single Filter">
    ```json
    [
      {
        "parameter": "country",
        "type": "equals",
        "value": ["US"]
      }
    ]
    ```
  </Tab>

  <Tab value="Multiple Filters">
    Multiple filters use AND logic:

    ```json
    [
      {
        "parameter": "country",
        "type": "equals",
        "value": ["US", "CA"]
      },
      {
        "parameter": "device_type",
        "type": "equals",
        "value": ["mobile"]
      }
    ]
    ```
  </Tab>

  <Tab value="Contains">
    Substring match:

    ```json
    [
      {
        "parameter": "pathname",
        "type": "contains",
        "value": ["/blog"]
      }
    ]
    ```
  </Tab>

  <Tab value="Regex">
    Pattern match:

    ```json
    [
      {
        "parameter": "pathname",
        "type": "regex",
        "value": ["^/products/[0-9]+$"]
      }
    ]
    ```
  </Tab>

  <Tab value="Numeric">
    Geolocation comparison:

    ```json
    [
      {
        "parameter": "lat",
        "type": "greater_than",
        "value": ["37.0"]
      },
      {
        "parameter": "lat",
        "type": "less_than",
        "value": ["38.0"]
      }
    ]
    ```
  </Tab>

  <Tab value="URL-encoded">
    ```
    ?filters=%5B%7B%22parameter%22%3A%22country%22%2C%22type%22%3A%22equals%22%2C%22value%22%3A%5B%22US%22%5D%7D%5D
    ```
  </Tab>
</Tabs>

***

## Error Responses [#error-responses]

All endpoints return standard HTTP status codes:

* **200** - Success
* **400** - Bad Request (invalid parameters)
* **401** - Unauthorized (missing or invalid API key)
* **403** - Forbidden (no access to site)
* **404** - Not Found (site doesn't exist)
* **429** - Too Many Requests (rate limit exceeded)
* **500** - Internal Server Error

### Error Response Format [#error-response-format]

```json
{
  "error": "Error message describing what went wrong"
}
```


# Build a Live Visitor Feed (/zh/docs/api/live-feed)





Rybbit doesn't push a websocket stream, but the events endpoint is built for polling: pass a `since_timestamp` and you get only the events that happened after it. This guide builds a self-advancing feed loop you can wire into a dashboard, a terminal ticker, or an alerting rule.

**Endpoints used:**

* [`GET /live-user-count`](/docs/api/overview/live-visitors) — how many visitors are active right now
* [`GET /events`](/docs/api/events/list) — the event stream, polled incrementally

## How incremental polling works [#how-incremental-polling-works]

The events endpoint returns the newest events first. To stream without duplicates, remember the timestamp of the most recent event you've seen and send it as `since_timestamp` on the next request — the API returns only events newer than that, up to 500 per call.

<Steps>
  <Step>
    **Fetch the initial batch** to establish a starting watermark (the newest timestamp).
  </Step>

  <Step>
    **On an interval, request events `since_timestamp`** = your watermark.
  </Step>

  <Step>
    **Process the new events** (print, render, alert) and advance the watermark to the newest one returned.
  </Step>
</Steps>

<Callout type="info">
  `since_timestamp` returns up to **500** events per call. If you expect more than 500 events between polls (a very high-traffic site with a long interval), poll more frequently so each batch stays under the cap.
</Callout>

## Full script [#full-script]

A Node script that prints a live count plus a rolling feed of activity. The same loop drives a browser dashboard — just replace `console.log` with DOM updates.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="live-feed.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const POLL_MS = 10000; // every 10 seconds

    async function get(path, params = {}) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    async function liveCount() {
      const { count } = await get('/live-user-count', { minutes: 5 });
      return count;
    }

    function describe(e) {
      const where = e.city ? `${e.city}, ${e.country}` : e.country || 'Unknown';
      if (e.type === 'pageview')     return `👀 viewed ${e.pathname} — ${where}`;
      if (e.type === 'custom_event') return `⚡ ${e.event_name} (${e.pathname}) — ${where}`;
      if (e.type === 'outbound')     return `↗️  left via ${e.pathname} — ${where}`;
      return `• ${e.type} — ${where}`;
    }

    let watermark = null; // ISO timestamp of the newest event we've shown

    async function poll() {
      try {
        const params = watermark ? { since_timestamp: watermark } : { page_size: 20 };
        const [{ data: events }, count] = await Promise.all([get('/events', params), liveCount()]);

        // Events come back newest-first; show oldest-first so the feed reads top-to-bottom
        for (const e of [...events].reverse()) {
          console.log(`[${new Date(e.timestamp).toLocaleTimeString()}] ${describe(e)}`);
        }
        if (events.length) watermark = events[0].timestamp; // newest event becomes the new watermark

        process.stdout.write(`\n🟢 ${count} visitors online\n`);
      } catch (err) {
        console.error('poll error:', err.message);
      }
    }

    console.log('Starting live feed… (Ctrl+C to stop)');
    poll();
    setInterval(poll, POLL_MS);
    ```
  </Tab>

  <Tab value="Python">
    ```python title="live_feed.py"
    import os, time
    from datetime import datetime
    import requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    POLL_SECONDS = 10

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def get(path, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def live_count():
        return get("/live-user-count", minutes=5)["count"]


    def describe(e):
        where = f'{e["city"]}, {e["country"]}' if e.get("city") else e.get("country") or "Unknown"
        if e["type"] == "pageview":
            return f'👀 viewed {e["pathname"]} — {where}'
        if e["type"] == "custom_event":
            return f'⚡ {e["event_name"]} ({e["pathname"]}) — {where}'
        if e["type"] == "outbound":
            return f'↗️  left via {e["pathname"]} — {where}'
        return f'• {e["type"]} — {where}'


    watermark = None  # ISO timestamp of the newest event we've shown

    print("Starting live feed… (Ctrl+C to stop)")
    while True:
        try:
            params = {"since_timestamp": watermark} if watermark else {"page_size": 20}
            events = get("/events", **params)["data"]

            # Events come back newest-first; show oldest-first so the feed reads top-to-bottom
            for e in reversed(events):
                ts = datetime.fromisoformat(e["timestamp"].replace("Z", "+00:00")).strftime("%H:%M:%S")
                print(f"[{ts}] {describe(e)}")
            if events:
                watermark = events[0]["timestamp"]  # newest event becomes the new watermark

            print(f"\n🟢 {live_count()} visitors online\n")
        except Exception as err:
            print(f"poll error: {err}")
        time.sleep(POLL_SECONDS)
    ```
  </Tab>
</Tabs>

## Example output [#example-output]

```text
Starting live feed… (Ctrl+C to stop)
[14:22:01] 👀 viewed /pricing — San Francisco, US
[14:22:03] ⚡ signup (/signup) — London, GB
[14:22:05] ↗️  left via /docs — Berlin, DE

🟢 42 visitors online
```

## Turn it into an alert [#turn-it-into-an-alert]

Because each poll hands you the raw events, you can act on them instead of just printing. For example, ping a channel whenever someone hits your enterprise pricing page:

<Tabs items="['JavaScript']">
  <Tab value="JavaScript">
    ```javascript title="React to specific events"
    for (const e of events) {
      if (e.type === 'pageview' && e.pathname === '/enterprise') {
        await fetch(process.env.SLACK_WEBHOOK, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            text: `🏢 Enterprise page visit from ${e.city || e.country} (${e.referrer || 'direct'})`,
          }),
        });
      }
    }
    ```
  </Tab>
</Tabs>

<Callout type="warn">
  **Mind the daily quota.** On Rybbit Cloud, a continuous poll is measured against your plan's daily quota (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only)), not just its per-second rate. A 10-second poll running around the clock is 8,640 requests/day — over the Standard quota of 5,000, and 17,280 with the live-count call added. Poll every 20-30 seconds, or only while someone is actually watching the page, and check `X-RateLimit-Daily-Remaining` to see where you stand. Self-hosted instances are not rate limited.
</Callout>

## Next steps [#next-steps]

* [Events API reference](/docs/api/events/list) — full event object fields, plus `before_timestamp` for scrolling backwards through history.
* [Export Raw Events to Your Warehouse](/docs/api/export-events) — the same `since_timestamp` mechanism, used for durable incremental syncs instead of a live view.


# Sending Events (/zh/docs/api/sending-events)





<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
  <div>
    ```
    POST /api/track
    ```

    Track pageviews, custom events, performance, and errors from server-side applications, mobile apps, or any platform. An API key is optional but recommended for server-side tracking — it bypasses bot detection and domain validation. IP addresses are resolved to geolocation and user agents are parsed for browser/OS/device info.

    ### Request Body [#request-body]

    All parameters are sent in the request body as JSON.

    <TypeTable
      type="{
  site_id: {
    description: 'Your site ID',
    type: 'string',
    required: true,
  },
  type: {
    description: 'Event type',
    type: 'string',
    typeDescription: '&#x22;pageview&#x22; | &#x22;custom_event&#x22; | &#x22;performance&#x22; | &#x22;outbound&#x22; | &#x22;error&#x22;',
    default: 'pageview',
  },
  pathname: {
    description: 'Page path',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  hostname: {
    description: 'Domain name',
    type: 'string',
    typeDescription: 'Max 253 chars',
  },
  page_title: {
    description: 'Page title',
    type: 'string',
    typeDescription: 'Max 512 chars',
  },
  referrer: {
    description: 'Referrer URL',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  user_id: {
    description: 'Custom user identifier',
    type: 'string',
    typeDescription: 'Max 255 chars',
  },
  user_agent: {
    description: 'Custom user agent string - will be parsed for browser/OS/device info',
    type: 'string',
    typeDescription: 'Max 512 chars',
  },
  ip_address: {
    description: 'Custom IP for geolocation - will be resolved to location data',
    type: 'string',
    typeDescription: 'Valid IPv4 or IPv6 address',
  },
  querystring: {
    description: 'Query parameters',
    type: 'string',
    typeDescription: 'Max 2048 chars',
  },
  language: {
    description: 'Language code',
    type: 'string',
    typeDescription: 'e.g., &#x22;en&#x22;, &#x22;es&#x22;, &#x22;fr&#x22;',
  },
  screenWidth: {
    description: 'Screen width in logical pixels (density-independent pixels)',
    type: 'number',
  },
  screenHeight: {
    description: 'Screen height in logical pixels (density-independent pixels)',
    type: 'number',
  },
  event_name: {
    description: 'Event name (required for custom events)',
    type: 'string',
    typeDescription: 'Max 256 chars',
  },
  properties: {
    description: 'JSON string with event data (for custom events, outbound, error)',
    type: 'string',
    typeDescription: 'Max 2048 chars (4096 for error events)',
  },
  feature_flags: {
    description: 'Optional map of feature flag keys to assigned values. Useful for server-side flag evaluation and filtering analytics by flag value.',
    type: 'Record<string, string>',
    typeDescription: 'Keys max 100 chars, values max 2048 chars',
  },
}"
    />

    #### Pageview [#pageview]

    Standard page view tracking. Set `type: "pageview"` (default).

    #### Custom Event [#custom-event]

    Track custom events with optional properties. Set `type: "custom_event"`.

    <TypeTable
      type="{
  event_name: {
    description: 'Name of the custom event',
    type: 'string',
    typeDescription: 'Max 256 chars',
    required: true,
  },
  properties: {
    description: 'Event data as JSON string',
    type: 'string',
    typeDescription: 'Valid JSON, max 2048 chars',
  },
}"
    />

    #### Performance [#performance]

    Track Core Web Vitals. Set `type: "performance"`.

    <TypeTable
      type="{
  lcp: {
    description: 'Largest Contentful Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  cls: {
    description: 'Cumulative Layout Shift score',
    type: 'number',
    typeDescription: 'nullable, typically 0-1',
  },
  inp: {
    description: 'Interaction to Next Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  fcp: {
    description: 'First Contentful Paint in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
  ttfb: {
    description: 'Time to First Byte in milliseconds',
    type: 'number',
    typeDescription: 'nullable',
  },
}"
    />

    #### Outbound [#outbound]

    Track outbound link clicks. Set `type: "outbound"`. Pass details in the `properties` JSON string.

    <TypeTable
      type="{
  url: {
    description: 'Destination URL',
    type: 'string',
    required: true,
  },
  text: {
    description: 'Link text content',
    type: 'string',
  },
  target: {
    description: 'Link target attribute',
    type: 'string',
    typeDescription: 'e.g., &#x22;_blank&#x22;, &#x22;_self&#x22;',
  },
}"
    />

    #### Error [#error]

    Track JavaScript errors. Set `type: "error"`. `event_name` is the error type and `properties` carries the error details as a JSON string.

    <TypeTable
      type="{
  message: {
    description: 'Error message',
    type: 'string',
    typeDescription: 'Max 500 chars',
    required: true,
  },
  stack: {
    description: 'Stack trace',
    type: 'string',
    typeDescription: 'Max 2000 chars',
  },
  fileName: {
    description: 'File where error occurred',
    type: 'string',
  },
  lineNumber: {
    description: 'Line number',
    type: 'number',
  },
  columnNumber: {
    description: 'Column number',
    type: 'number',
  },
}"
    />

    ### Response [#response]

    <TypeTable
      type="{
  success: {
    description: 'Whether the event was accepted',
    type: 'boolean',
  },
}"
    />

    ### Rate Limiting [#rate-limiting]

    API keys are limited to **500 requests per 10 minutes**. Exceeding the limit returns a `429` status code.
  </div>

  <div className="flex flex-col gap-4">
    <Tabs items="['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']">
      <Tab value="cURL">
        ```bash title="Request"
        curl -X POST "https://app.rybbit.io/api/track" \
          -H "Authorization: Bearer your_api_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "site_id": "1",
            "type": "custom_event",
            "pathname": "/checkout",
            "event_name": "purchase",
            "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```javascript title="Request"
        const response = await fetch('https://app.rybbit.io/api/track', {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer your_api_key_here',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            site_id: '1',
            type: 'custom_event',
            pathname: '/checkout',
            event_name: 'purchase',
            properties: JSON.stringify({ amount: 99.99, currency: 'USD' })
          })
        });

        const data = await response.json();
        ```
      </Tab>

      <Tab value="Python">
        ```python title="Request"
        import requests
        import json

        response = requests.post(
            'https://app.rybbit.io/api/track',
            json={
                'site_id': '1',
                'type': 'custom_event',
                'pathname': '/checkout',
                'event_name': 'purchase',
                'properties': json.dumps({'amount': 99.99, 'currency': 'USD'})
            },
            headers={
                'Authorization': 'Bearer your_api_key_here'
            }
        )

        data = response.json()
        ```
      </Tab>

      <Tab value="PHP">
        ```php title="Request"
        $body = [
            'site_id' => '1',
            'type' => 'custom_event',
            'pathname' => '/checkout',
            'event_name' => 'purchase',
            'properties' => json_encode(['amount' => 99.99, 'currency' => 'USD'])
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, 'https://app.rybbit.io/api/track');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer your_api_key_here',
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);
        ```
      </Tab>

      <Tab value="Ruby">
        ```ruby title="Request"
        require 'net/http'
        require 'json'

        uri = URI('https://app.rybbit.io/api/track')
        request = Net::HTTP::Post.new(uri)
        request['Authorization'] = 'Bearer your_api_key_here'
        request['Content-Type'] = 'application/json'
        request.body = {
          site_id: '1',
          type: 'custom_event',
          pathname: '/checkout',
          event_name: 'purchase',
          properties: { amount: 99.99, currency: 'USD' }.to_json
        }.to_json

        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
          http.request(request)
        end

        data = JSON.parse(response.body)
        ```
      </Tab>

      <Tab value="Go">
        ```go title="Request"
        body := map[string]interface{}{
            "site_id":    "1",
            "type":       "custom_event",
            "pathname":   "/checkout",
            "event_name": "purchase",
            "properties": `{"amount": 99.99, "currency": "USD"}`,
        }
        jsonBody, _ := json.Marshal(body)

        req, _ := http.NewRequest("POST", "https://app.rybbit.io/api/track", bytes.NewBuffer(jsonBody))
        req.Header.Set("Authorization", "Bearer your_api_key_here")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()

        var data map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&data)
        ```
      </Tab>

      <Tab value="Rust">
        ```rust title="Request"
        let body = serde_json::json!({
            "site_id": "1",
            "type": "custom_event",
            "pathname": "/checkout",
            "event_name": "purchase",
            "properties": r#"{"amount": 99.99, "currency": "USD"}"#
        });

        let client = reqwest::Client::new();
        let res = client
            .post("https://app.rybbit.io/api/track")
            .header("Authorization", "Bearer your_api_key_here")
            .json(&body)
            .send()
            .await?;

        let data: serde_json::Value = res.json().await?;
        ```
      </Tab>

      <Tab value="Java">
        ```java title="Request"
        String json = """
        {
          "site_id": "1",
          "type": "custom_event",
          "pathname": "/checkout",
          "event_name": "purchase",
          "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.rybbit.io/api/track"))
            .header("Authorization", "Bearer your_api_key_here")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        ```
      </Tab>

      <Tab value=".NET">
        ```csharp title="Request"
        var body = new
        {
            site_id = "1",
            type = "custom_event",
            pathname = "/checkout",
            event_name = "purchase",
            properties = JsonSerializer.Serialize(new { amount = 99.99, currency = "USD" })
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

        var content = new StringContent(
            JsonSerializer.Serialize(body),
            Encoding.UTF8,
            "application/json");

        var response = await client.PostAsync("https://app.rybbit.io/api/track", content);
        var data = await response.Content.ReadAsStringAsync();
        ```
      </Tab>
    </Tabs>

    ```json title="Success"
    {
      "success": true
    }
    ```

    ```json title="Error"
    {
      "success": false,
      "error": "Invalid payload",
      "details": {
        "fieldErrors": {},
        "formErrors": ["Custom events require event_name"]
      }
    }
    ```
  </div>
</div>


# Automated Weekly Report (/zh/docs/api/weekly-report)





This guide builds a script you can run on a schedule (a cron job, GitHub Action, or serverless function) that pulls last week's numbers, compares them to the week before, and posts a digest to Slack, email, or anywhere else.

**Endpoints used:**

* [`GET /overview`](/docs/api/overview/overview) — headline metrics for a date range
* [`GET /metric`](/docs/api/overview/metric) — top pages and traffic sources

<Callout type="info">
  Every analytics endpoint takes the same [time parameters](/docs/api/getting-started#time-parameters). The trick behind any comparison report is simply calling the same endpoint twice with two adjacent date ranges.
</Callout>

## The workflow [#the-workflow]

<Steps>
  <Step>
    **Fetch this week's overview** for the last 7 days.
  </Step>

  <Step>
    **Fetch last week's overview** for the 7 days before that, so you can compute the change.
  </Step>

  <Step>
    **Fetch top pages and top sources** from the `metric` endpoint to add context.
  </Step>

  <Step>
    **Format and deliver** the digest.
  </Step>
</Steps>

## Full script [#full-script]

This example posts a formatted message to a Slack incoming webhook, but the `buildReport` function returns plain data you can route anywhere.

<Tabs items="['JavaScript', 'Python']">
  <Tab value="JavaScript">
    ```javascript title="weekly-report.js"
    const API = 'https://app.rybbit.io';
    const SITE = '123';
    const API_KEY = process.env.RYBBIT_API_KEY;
    const SLACK_WEBHOOK = process.env.SLACK_WEBHOOK;
    const TZ = 'America/New_York';

    // Helper: format a Date as YYYY-MM-DD
    const ymd = (d) => d.toISOString().slice(0, 10);

    async function get(path, params) {
      const url = new URL(`${API}/api/sites/${SITE}${path}`);
      Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
      const res = await fetch(url, {
        headers: { Authorization: `Bearer ${API_KEY}` },
      });
      if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
      return res.json();
    }

    async function overview(start, end) {
      const { data } = await get('/overview', {
        start_date: ymd(start),
        end_date: ymd(end),
        time_zone: TZ,
      });
      return data;
    }

    async function topMetric(parameter, start, end, limit = 5) {
      const { data } = await get('/metric', {
        parameter,
        start_date: ymd(start),
        end_date: ymd(end),
        time_zone: TZ,
        limit,
      });
      return data.data; // metric nests results under data.data
    }

    function pctChange(current, previous) {
      if (!previous) return null;
      return ((current - previous) / previous) * 100;
    }

    async function buildReport() {
      const now = new Date();
      const thisWeekStart = new Date(now); thisWeekStart.setDate(now.getDate() - 7);
      const lastWeekEnd   = new Date(now); lastWeekEnd.setDate(now.getDate() - 8);
      const lastWeekStart = new Date(now); lastWeekStart.setDate(now.getDate() - 14);

      const [thisWeek, lastWeek, topPages, topSources] = await Promise.all([
        overview(thisWeekStart, now),
        overview(lastWeekStart, lastWeekEnd),
        topMetric('pathname', thisWeekStart, now),
        topMetric('referrer', thisWeekStart, now),
      ]);

      return {
        sessions: { value: thisWeek.sessions, change: pctChange(thisWeek.sessions, lastWeek.sessions) },
        users:    { value: thisWeek.users,    change: pctChange(thisWeek.users, lastWeek.users) },
        pageviews:{ value: thisWeek.pageviews, change: pctChange(thisWeek.pageviews, lastWeek.pageviews) },
        bounceRate: thisWeek.bounce_rate,
        topPages,
        topSources,
      };
    }

    function arrow(change) {
      if (change === null) return '';
      const sign = change >= 0 ? '▲' : '▼';
      return ` ${sign} ${Math.abs(change).toFixed(1)}%`;
    }

    async function postToSlack(r) {
      const lines = [
        `*📊 Weekly Analytics Report*`,
        ``,
        `• Sessions: *${r.sessions.value.toLocaleString()}*${arrow(r.sessions.change)}`,
        `• Unique users: *${r.users.value.toLocaleString()}*${arrow(r.users.change)}`,
        `• Pageviews: *${r.pageviews.value.toLocaleString()}*${arrow(r.pageviews.change)}`,
        `• Bounce rate: *${r.bounceRate.toFixed(1)}%*`,
        ``,
        `*Top pages*`,
        ...r.topPages.map((p) => `   ${p.value} — ${p.count.toLocaleString()}`),
        ``,
        `*Top sources*`,
        ...r.topSources.map((s) => `   ${s.value || 'Direct'} — ${s.count.toLocaleString()}`),
      ];
      await fetch(SLACK_WEBHOOK, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text: lines.join('\n') }),
      });
    }

    buildReport().then(postToSlack).catch(console.error);
    ```
  </Tab>

  <Tab value="Python">
    ```python title="weekly_report.py"
    import os
    from datetime import datetime, timedelta
    import requests

    API = "https://app.rybbit.io"
    SITE = "123"
    API_KEY = os.environ["RYBBIT_API_KEY"]
    SLACK_WEBHOOK = os.environ["SLACK_WEBHOOK"]
    TZ = "America/New_York"

    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {API_KEY}"


    def ymd(d: datetime) -> str:
        return d.strftime("%Y-%m-%d")


    def get(path: str, **params):
        res = session.get(f"{API}/api/sites/{SITE}{path}", params=params)
        res.raise_for_status()
        return res.json()


    def overview(start, end):
        return get("/overview", start_date=ymd(start), end_date=ymd(end), time_zone=TZ)["data"]


    def top_metric(parameter, start, end, limit=5):
        # metric nests results under data.data
        return get("/metric", parameter=parameter, start_date=ymd(start),
                   end_date=ymd(end), time_zone=TZ, limit=limit)["data"]["data"]


    def pct_change(current, previous):
        return None if not previous else (current - previous) / previous * 100


    def build_report():
        now = datetime.utcnow()
        this_start = now - timedelta(days=7)
        last_end = now - timedelta(days=8)
        last_start = now - timedelta(days=14)

        this_week = overview(this_start, now)
        last_week = overview(last_start, last_end)

        return {
            "sessions": (this_week["sessions"], pct_change(this_week["sessions"], last_week["sessions"])),
            "users": (this_week["users"], pct_change(this_week["users"], last_week["users"])),
            "pageviews": (this_week["pageviews"], pct_change(this_week["pageviews"], last_week["pageviews"])),
            "bounce_rate": this_week["bounce_rate"],
            "top_pages": top_metric("pathname", this_start, now),
            "top_sources": top_metric("referrer", this_start, now),
        }


    def arrow(change):
        if change is None:
            return ""
        return f" {'▲' if change >= 0 else '▼'} {abs(change):.1f}%"


    def post_to_slack(r):
        lines = [
            "*📊 Weekly Analytics Report*", "",
            f"• Sessions: *{r['sessions'][0]:,}*{arrow(r['sessions'][1])}",
            f"• Unique users: *{r['users'][0]:,}*{arrow(r['users'][1])}",
            f"• Pageviews: *{r['pageviews'][0]:,}*{arrow(r['pageviews'][1])}",
            f"• Bounce rate: *{r['bounce_rate']:.1f}%*", "",
            "*Top pages*",
            *[f"   {p['value']} — {p['count']:,}" for p in r["top_pages"]], "",
            "*Top sources*",
            *[f"   {s['value'] or 'Direct'} — {s['count']:,}" for s in r["top_sources"]],
        ]
        requests.post(SLACK_WEBHOOK, json={"text": "\n".join(lines)})


    post_to_slack(build_report())
    ```
  </Tab>
</Tabs>

## Example output [#example-output]

```text
📊 Weekly Analytics Report

• Sessions: 15,420 ▲ 12.3%
• Unique users: 12,847 ▲ 9.8%
• Pageviews: 48,933 ▼ 2.1%
• Bounce rate: 42.8%

Top pages
   / — 8,230
   /pricing — 3,120
   /blog/getting-started — 1,940

Top sources
   google.com — 6,410
   Direct — 4,220
   twitter.com — 1,180
```

## Schedule it [#schedule-it]

Run the script every Monday morning with cron:

```bash title="crontab -e"
# Every Monday at 9:00 AM
0 9 * * 1 RYBBIT_API_KEY=xxx SLACK_WEBHOOK=https://hooks.slack.com/... node /path/to/weekly-report.js
```

<Callout type="info">
  **Want a richer report?** The same pattern extends naturally. Add `topMetric('channel', ...)` for marketing channels, `topMetric('country', ...)` for geography, or call the [`time-series` endpoint](/docs/api/overview/time-series) with `bucket=day` to attach a 7-point trend line.
</Callout>

## Next steps [#next-steps]

* [Compare Marketing Channel Performance](/docs/api/channel-performance) — go beyond traffic counts and rank sources by how well they convert.
* [Export Raw Events to Your Warehouse](/docs/api/export-events) — if you'd rather build reports in your own BI tool.


# Dashboard Embed (/zh/docs/embeds/dashboard)





The dashboard embed lets you place the main Rybbit analytics dashboard on another site with a self-contained iframe. Dashboard embeds use private-link routes with `embed=true`.

## Try It Out [#try-it-out]

Configure the private-link dashboard embed URL below. The generated snippet uses the same private-link route created in the Rybbit dashboard.

<DashboardEmbedDemo />

## Requirements [#requirements]

Dashboard embeds require a generated private link. The private link key is included in the route, for example `/{siteId}/{privateLinkKey}/main`.

Unlike [Widget Embeds](/docs/embeds/widget), dashboard embeds expose the full read-only analytics dashboard, not just the compact live visitor widget.

<Callout type="warn">
  Private links are not listed publicly, but anyone with the private link can view the dashboard. Treat the iframe URL like a shareable read-only secret.
</Callout>

## Setup [#setup]

1. Open your site in the Rybbit dashboard and click the settings icon.
2. Go to the **Dashboard Embed** tab.
3. Generate a private link if one does not already exist.
4. Choose the embed theme: light, dark, or system.
5. Choose whether to hide the dashboard sidebar.
6. Copy the generated `<iframe>` snippet and paste it anywhere on your site.

## Appearance [#appearance]

* **Theme**: `light`, `dark`, or `system`. `system` follows the viewer's operating system color-scheme preference.
* **Hide sidebar**: removes the dashboard sidebar and keeps viewers on the main dashboard page.
* **Footer**: the Rybbit footer is hidden automatically in embed mode.

## Example [#example]

```html
<iframe
  src="https://app.rybbit.io/YOUR_SITE_ID/YOUR_PRIVATE_LINK_KEY/main?embed=true&theme=system&hideSidebar=true"
  style="border: 0; width: 100%; height: 720px;"
  loading="lazy"
  title="Analytics dashboard"
></iframe>
```

If you self-host Rybbit, replace `app.rybbit.io` with your own domain.

## URL Parameters [#url-parameters]

| Parameter     | Values                    | Description                                                               |
| ------------- | ------------------------- | ------------------------------------------------------------------------- |
| `embed`       | `true`                    | Enables embed mode                                                        |
| `theme`       | `light`, `dark`, `system` | Sets the embedded dashboard color scheme. Defaults to `system`            |
| `hideSidebar` | `true`, `false`           | Hides the dashboard sidebar and keeps visitors on the main dashboard page |

When `hideSidebar=true`, only the main dashboard page is shown in the iframe. Leave it off if you want viewers to use the dashboard sidebar to navigate other analytics pages allowed by the private link.

The private key is part of the path, not a query parameter: `/{siteId}/{privateLinkKey}/main?embed=true`.


# Widget Embeds (/zh/docs/embeds/widget)





Widget Embeds let you place a compact live visitor widget on another site with a self-contained iframe. There is no script tag, no JavaScript on your site, and no dependency on the Rybbit tracking script.

## Try It [#try-it]

Configure the widget below to see how it'll look. The preview shows live data from [demo.rybbit.com](https://demo.rybbit.com).

<EmbedWidgetDemo />

## Requirements [#requirements]

The widget needs a public read-only data endpoint, so you must enable **Widget Embeds** on the site. This is separate from **Public Analytics**. Turning it on only exposes the live count, time series, and top countries to the widget endpoint, not your full dashboard.

<Callout type="info">
  Enabling Widget Embeds does **not** make your dashboard public. Only the data shown in the widget itself (visitor count, per-minute / per-hour / per-day series, top 5 countries) is accessible; no individual sessions, events, pages, or referrers are exposed.
</Callout>

## Setup [#setup]

1. Open your site in the Rybbit dashboard and click the settings icon.
2. Go to the **Widget Embeds** tab.
3. Toggle **Widget Enabled** on.
4. Pick your options: variant, time window, theme, accent color, and display settings.
5. Copy the generated `<iframe>` snippet and paste it anywhere on your site.

## Variants [#variants]

### Card [#card]

A self-contained dashboard card showing the live count, an optional bar chart of users over time, and an optional list of top countries.

| Option        | Values                         | Default | Description                                              |
| ------------- | ------------------------------ | ------- | -------------------------------------------------------- |
| Time window   | 30 minutes / 24 hours / 7 days | 30 min  | Window the count and chart cover                         |
| Bar chart     | on / off                       | on      | Show a bar chart bucketed per minute / hour / day        |
| Top countries | on / off                       | on      | List the top 5 countries in the window                   |
| Width         | 240-800 px                     | 360 px  | Iframe width; use `max-width: 100%` for responsive sites |

### Inline Pill [#inline-pill]

A compact pill that fits inline with your site's chrome, such as in a header or footer. It shows the pulsing dot, the live count over the last 30 minutes, and the Rybbit logo.

## Appearance [#appearance]

* **Theme**: `dark` or `light`. The widget background is transparent, so rounded-corner edges blend into whatever sits behind the iframe.
* **Accent color**: any hex color. Used for the pulsing live-indicator dot and the bar-chart bars. Defaults to Rybbit emerald.

## Example [#example]

```html
<iframe
  src="https://app.rybbit.io/widget/YOUR_SITE_ID?variant=card&theme=dark&minutes=30&chart=true&countries=true"
  style="border: 0; width: 360px; height: 390px; max-width: 100%;"
  loading="lazy"
  title="Live visitors"
></iframe>
```

If you self-host Rybbit, replace `app.rybbit.io` with your own domain.

## URL Parameters [#url-parameters]

You don't usually need to build the URL by hand because the dashboard generates the snippet for you, but the widget URL accepts these parameters:

| Parameter   | Values                                 | Description                               |
| ----------- | -------------------------------------- | ----------------------------------------- |
| `variant`   | `card`, `inline`                       | Layout variant                            |
| `theme`     | `dark`, `light`                        | Color scheme                              |
| `accent`    | 6-character hex, no `#`, e.g. `10b981` | Pulse / bar color                         |
| `minutes`   | `30`, `1440`, `10080`                  | Time window in minutes, card variant only |
| `chart`     | `true`, `false`                        | Show the bar chart, card variant only     |
| `countries` | `true`, `false`                        | Show top countries, card variant only     |

## Caching [#caching]

The widget HTML and the underlying stats endpoint are both cached for 60 seconds on the server, so embedding the widget on a high-traffic page won't put pressure on your Rybbit instance. The visible count refreshes once per minute.


# Errors (/zh/docs/feature-guides/errors)



The Errors tab shows JavaScript errors occurring on your website, helping you identify and fix bugs that affect user experience.

## Enabling Error Tracking [#enabling-error-tracking]

Enable error tracking in your [site settings](/docs/site-settings).

## Error Information [#error-information]

For each error, you'll see:

* **Error Type** - ReferenceError, TypeError, SyntaxError, NetworkError, etc.
* **Error Message** - The specific error message
* **Stack Trace** - The chain of function calls that led to the error
* **Affected Sessions** - Number of unique sessions in which this error occurred
* **Occurrence Count** - How many times the error was triggered
  Expanding an error shows its individual occurrences, including the timestamp and page for each event.
* **Browser & Device** - Which environments experience this error

## Using Error Data [#using-error-data]

* **Prioritize by impact** - Fix errors affecting the most users first
* **Monitor after deployments** - Watch for new errors after releasing code
* **Debug user reports** - Find the exact technical issue when users report problems
* **Track third-party issues** - Identify when external integrations are malfunctioning


# Events (/zh/docs/feature-guides/events)



The Events tab shows custom events tracked on your website.

## Setting Up Events [#setting-up-events]

See the [Track Events guide](/docs/track-events) for implementation details.

## Events Page [#events-page]

The events page includes:

* **Events Chart** - Visualize event trends over time
* **Event Log** - Recent individual event occurrences (click any row to open a details sheet)

The **Custom Events List** — all tracked events with counts — lives in the Events section of the main dashboard.

## Event Metrics [#event-metrics]

For each event in the Custom Events List:

* **Event Name** - The name you assigned to the event
* **Count** - Total times triggered in the selected period
* **Percentage** - Share of total events

## Event Properties [#event-properties]

In the Custom Events List, click the expand arrow on any event to view its properties. Properties show the key-value pairs attached to events, helping you understand event context (e.g., which product was purchased, what button was clicked).

## Filtering [#filtering]

* Click any event name to filter the dashboard to sessions containing that event
* Use the filter panel to combine event filters with other dimensions
* Filter by time range to analyze event trends


# Globe (/zh/docs/feature-guides/globe)



The Globe tab shows where your visitors connect from on an interactive map.

## View Modes [#view-modes]

### 2D Map [#2d-map]

* **Timeline** - View sessions by timeframe, click individual sessions for details
* **Coordinates** - Sessions as dots with color intensity showing traffic volume
* **Countries** - Countries highlighted by traffic volume
* **Subdivisions** - Granular view by national subdivisions

### 3D Globe [#3d-globe]

Same four views as 2D, plus:

* Rotate by dragging
* Zoom in and out
* Traffic hotspots glow

The 3D view requires a Mapbox API token. Self-hosted installations need `MAPBOX_TOKEN` in environment variables. Cloud includes this automatically.

## Time Controls [#time-controls]

Pick date ranges to see how geographic distribution changes over time.

## Filtering [#filtering]

Apply the same filters as the main dashboard to see geographic distribution for specific segments.


# User Journeys (/zh/docs/feature-guides/journeys)





<img alt="User Journeys Dashboard" src="__img0" />

User journeys show the actual paths people take as they move through your website, revealing how they flow from page to page.

## Reading the Visualization [#reading-the-visualization]

### Nodes [#nodes]

Each bar represents a page or event. Its height indicates how many users reached that point.

### Connections [#connections]

Lines between nodes show user flow. Thicker connections mean more users took that path.

### Flow Direction [#flow-direction]

The visualization flows left to right, showing progression through time.

## Key Patterns to Look For [#key-patterns-to-look-for]

* **Happy Path** - The most common route to conversion
* **Drop-off Points** - Where many users enter but few continue
* **Backtracking** - Users moving backward, often indicating confusion
* **Alternative Routes** - Unexpected paths to important pages

## Using Journey Insights [#using-journey-insights]

* **Simplify complex paths** - Create shortcuts to important pages
* **Fix drop-off points** - Investigate why users leave at certain pages
* **Amplify successful paths** - Make high-converting routes easier to follow
* **Reduce backtracking** - Improve navigation where users get lost

## Analysis Types [#analysis-types]

* **Entry point analysis** - Where do users go from a specific page?
* **Goal-based analysis** - How did converting users get there?
* **Full journey mapping** - Overall flow from entry to exit


# Main Dashboard (/zh/docs/feature-guides/main-tab)





<img alt="Main Dashboard" src="__img0" />

The main dashboard is your home base in Rybbit Analytics, showing all key metrics at a glance.

## Top Metrics [#top-metrics]

* **Unique Users** - Different people who visited your site
* **Total Sessions** - Number of visits (30-minute inactivity starts a new session)
* **Total Pageviews** - Every page load from every visitor
* **Bounce Rate** - Percentage of single-page sessions
* **Pages Per Session** - Average pages viewed per visit
* **Session Duration** - Average time spent per visit

## Time Controls [#time-controls]

Select date ranges: Today, Yesterday, Last 7/30/60 days, This Week, This Month, All Time, or a custom range.

## Filters [#filters]

Combine filters for granular analysis:

* Device type, browser, OS
* Country, city
* Referrer, UTM parameters
* Custom event properties

A set of filters you use often can be saved as a [segment](/docs/segments) from the **Segments** tab of the Filter button, then applied to any report with one click.

## Main Chart [#main-chart]

Shows your selected metric over time. Click the metric selector to switch between Users, Sessions, Pageviews, Bounce Rate, Pages Per Session, or Session Duration.

## Traffic Sources [#traffic-sources]

See where your traffic comes from:

* **Direct** - Typed URL or bookmarks
* **Search** - Google, Bing, DuckDuckGo, etc.
* **Social** - Twitter, Facebook, LinkedIn, Reddit
* **Referral** - Other websites

Click any source to filter the entire dashboard to that traffic.

## UTM Parameters [#utm-parameters]

View campaign data: utm\_campaign, utm\_source, utm\_medium, utm\_term, utm\_content.

## Additional Breakdowns [#additional-breakdowns]

* **Top Pages** - Most visited URLs with pageviews, visitors, time on page, and bounce rate
* **Entry/Exit Pages** - Where visits begin and end
* **Devices & Browsers** - Desktop/mobile/tablet split, browser and OS breakdown
* **Screen Resolutions** - What sizes your visitors use
* **Geographic Data** - Countries and regions
* **Custom Events** - Click any event to filter to sessions containing it


# Pages (/zh/docs/feature-guides/pages-tab)





<img alt="Pages Dashboard" src="__img0" />

The Pages tab shows detailed analytics for every URL on your site.

## Page Metrics [#page-metrics]

Each page displays:

* **Page URL** - The full path
* **Sessions** - Number of sessions that viewed this page
* **Average Time on Page** - How long visitors spend there

## Filtering [#filtering]

Use the same filters as the main dashboard to analyze specific segments:

* Mobile users from social media
* Desktop users who converted
* Users who triggered specific events

## Identifying Issues [#identifying-issues]

* Scan for pages with low time on page to find content that isn't engaging
* Look for pages with few sessions to find underperforming pages
* Compare entry pages to see which content attracts traffic


# Performance (/zh/docs/feature-guides/performance)





<img alt="Performance Dashboard" src="__img0" />

The Performance tab tracks Core Web Vitals from real user data.

## Enabling Performance Tracking [#enabling-performance-tracking]

Enable Web Vitals in your [site settings](/docs/site-settings).

## Web Vitals [#web-vitals]

### Largest Contentful Paint (LCP) [#largest-contentful-paint-lcp]

How long the main content takes to load.

* **Good**: Under 2.5 seconds
* **Needs Improvement**: 2.5-4 seconds
* **Poor**: Over 4 seconds

### Cumulative Layout Shift (CLS) [#cumulative-layout-shift-cls]

How much content jumps around while loading.

* **Good**: Under 0.1
* **Needs Improvement**: 0.1-0.25
* **Poor**: Over 0.25

### Interaction to Next Paint (INP) [#interaction-to-next-paint-inp]

How quickly your site responds to user interactions.

* **Good**: Under 200ms
* **Needs Improvement**: 200-500ms
* **Poor**: Over 500ms

### First Contentful Paint (FCP) [#first-contentful-paint-fcp]

How long until the first content appears.

* **Good**: Under 1.8 seconds
* **Needs Improvement**: 1.8-3 seconds
* **Poor**: Over 3 seconds

### Time to First Byte (TTFB) [#time-to-first-byte-ttfb]

How long until the server responds.

* **Good**: Under 800ms
* **Needs Improvement**: 800-1800ms
* **Poor**: Over 1800ms

## Percentile Selector [#percentile-selector]

Choose which percentile to view (p50, p75, p90, p99). The p75 is commonly used for Core Web Vitals assessment.

## Comparison [#comparison]

Each metric shows the change from the previous period, with green indicating improvement and red indicating degradation.

## Breakdowns [#breakdowns]

* **By Page** - Find your slowest pages
* **By Device** - Compare mobile vs desktop performance
* **By Browser** - Identify browser-specific issues
* **By Country** - See geographic performance differences


# Retention (/zh/docs/feature-guides/retention)





<img alt="Retention Dashboard" src="__img0" />

Retention analysis shows how many users come back to your site over time, revealing whether users find lasting value.

## Understanding Cohorts [#understanding-cohorts]

A cohort is a group of users who share a common start date. For example, all users who first visited on January 15th form one cohort.

## Reading the Retention Table [#reading-the-retention-table]

### Rows [#rows]

Each row is a different cohort, grouped by first visit date.

### Columns [#columns]

* **Day/Week 0** - Starting point (always 100%)
* **Day/Week 1, 2, 3...** - Users who returned after that period

### Numbers [#numbers]

Percentages show what portion of the original cohort returned. 40% in the "Day 7" column means 40% of users came back after a week.

### Color Coding [#color-coding]

* Lighter colors = higher retention
* Darker colors = more drop-off

## Key Insights [#key-insights]

* **Day 1 retention** - Did users find enough value to return the next day?
* **Day 7 retention** - Did users integrate your product into their routine?
* **Day 30 retention** - Have users formed a habit?

## Common Patterns [#common-patterns]

* **Cliff drop** - Sharp decline in first few days indicates onboarding issues
* **Steady decline** - Gradual drop suggests novelty wearing off
* **Plateau** - When retention levels off, you've found your core users

## Note on User ID Salting [#note-on-user-id-salting]

If [User ID Salting](/docs/site-settings) is enabled, retention beyond 24 hours becomes less accurate since user identifiers reset daily.


# Session Replay (/zh/docs/feature-guides/session-replay)





<img alt="Session Replay" src="__img0" />

Session replay lets you watch anonymized recordings of real user sessions, showing mouse movements, clicks, scrolls, and page navigation.

## Enabling Session Replay [#enabling-session-replay]

Enable session replay in your [site settings](/docs/site-settings). The tracking script picks the setting up automatically — no script tag changes are needed. (Script-tag attributes like `data-replay-batch-size` and the `data-replay-mask-*` options only tune replay behavior; the on/off switch lives in site settings.)

## What You'll See [#what-youll-see]

* Mouse movements and clicks
* Scrolling behavior
* Page navigation
* Form interactions (with PII masked)
* User details: country, device, browser

## Using Session Replay [#using-session-replay]

* **UX optimization** - Identify where users get stuck or confused
* **Debug issues** - See exactly what happened when users report problems
* **Understand behavior** - Go beyond metrics to see the full user story
* **Share with your team** - Collaborate on findings

## Privacy [#privacy]

Session replay automatically masks sensitive information. Enable PII protection in your settings for additional masking of form inputs and text content.


# Sessions (/zh/docs/feature-guides/sessions)



The Sessions tab shows individual user visits to your website, including all page views, interactions, and events during each session.

## Session Metrics [#session-metrics]

Each session displays:

* **Duration** - Time spent on site
* **Pages Visited** - Number of pages viewed
* **Events Triggered** - Custom events fired during the session
* **Device & Browser** - Technical environment
* **Location** - Geographic location based on IP
* **Entry/Exit Page** - Where the session started and ended
* **Bounce Status** - Whether the user left after one page

## Filtering Sessions [#filtering-sessions]

Filter by:

* Duration, pages visited, or events triggered
* Device type, browser, or location
* Referrer or traffic source
* Date range

## Session Replay [#session-replay]

If [session replay](/docs/product-analytics/replay-session) is enabled, you can watch a recording of any session to see exactly what the user did.


# Users (/zh/docs/feature-guides/users)



The Users tab shows unique visitors and their behavior across multiple sessions.

## User Metrics [#user-metrics]

For each user, you'll see:

* **User ID** - Anonymized identifier
* **First/Last Visit** - When they first and most recently visited
* **Total Sessions** - Number of separate visits
* **Pages Viewed** - Total pages across all sessions
* **Events Triggered** - Total custom events
* **Device Type** - Desktop, mobile, or tablet
* **Location** - Geographic location

## Filtering Users [#filtering-users]

Filter by the standard dimension filters:

* Device type, browser, or operating system
* Country, region, or city
* Referrer, channel, or UTM parameters
* Pages visited (pathname, entry, or exit page)

Session count, pageviews, events, and first/last seen aren't filters, but you can sort the user list by those columns.

## Identified Users [#identified-users]

If you use the [identify API](/docs/identify-users), you can see your own user IDs alongside the anonymous identifiers.


# Claude Code (/zh/docs/mcp/claude-code)



Connecting Claude Code to Rybbit lets it answer analytics questions mid-task — whether the error it just fixed still occurs in production, which pages get traffic before a refactor, whether a newly instrumented event is firing — and wire up goals and funnels as you ship features.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

The simplest way to connect — no API key to create or store:

```bash
claude mcp add --transport http rybbit https://app.rybbit.io/api/mcp
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Then run `/mcp` inside a Claude Code session, select **rybbit**, and choose **Authenticate**. Your browser opens to log in to Rybbit and approve access, and the connection acts with your user's role.

By default the server registers at the `local` scope — available to you in the current project only. Add `--scope user` to use it in all of your projects.

## Team setup [#team-setup]

OAuth makes the team setup trivial: commit a project-scoped `.mcp.json` at the repository root containing only the URL, and each developer authenticates once with `/mcp`. No secret ever touches the repo:

```json
{
  "mcpServers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp"
    }
  }
}
```

## Connect with an API key [#connect-with-an-api-key]

Use an [API key](/docs/mcp#1-create-an-api-key) instead when there is no browser to authenticate in (CI, headless `claude -p` runs) or when you want to hand the agent a narrower, scoped credential:

```bash
claude mcp add --transport http rybbit https://app.rybbit.io/api/mcp \
  --header "Authorization: Bearer <RYBBIT_API_KEY>"
```

In a committed `.mcp.json`, pass the key through an environment variable rather than hard-coding it — Claude Code expands `${VAR}` references from each developer's environment:

```json
{
  "mcpServers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${RYBBIT_API_KEY}"
      }
    }
  }
}
```

## Verify [#verify]

Run `claude mcp list` (or `/mcp` inside a session) to confirm the server shows as connected, then try:

> List my Rybbit sites and summarize last week's traffic for each.


# Claude Desktop (/zh/docs/mcp/claude-desktop)





Adding Rybbit as a custom connector turns Claude into a conversational analytics interface: ask how a launch went, why traffic spiked on Tuesday, or where a funnel drops off — without opening the dashboard. Connectors are shared across claude.ai, Claude Desktop, and the mobile apps.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, the full tool list, permissions, and troubleshooting.

## Add the connector [#add-the-connector]

1. Open **Settings → Connectors** (in Claude Desktop: `Cmd/Ctrl + ,`, then **Connectors**; on claude.ai: your profile menu → **Settings** → **Connectors**).

2. Click **Add custom connector**.

3. Name it **Rybbit** and paste the endpoint URL:

   ```text
   https://app.rybbit.io/api/mcp
   ```

   For a self-hosted installation, use your configured `BASE_URL` host instead.

4. Confirm, then click **Connect**. Your browser opens Rybbit's [OAuth flow](/docs/mcp#or-connect-with-oauth) — log in and approve access. The connector acts with your user's role.

There is no API key to manage: custom connectors authenticate through OAuth, and the **Advanced settings** fields (OAuth client ID and secret) can stay empty — Rybbit registers the client automatically. Custom connectors are available on all Claude plans; the Free plan is limited to one.

<Callout type="warn">
  **Self-hosted installations must be publicly reachable.** Claude connects to
  custom connectors from Anthropic's infrastructure, not from your device — a
  Rybbit instance on a private network, behind a VPN, or on `localhost` will
  not connect, even if you can reach it in your own browser.
</Callout>

## Use it [#use-it]

Once connected, Rybbit appears in the chat's tools menu — enable it there if it isn't already. Then try:

> List my Rybbit sites and summarize last month's traffic for the main one.

Claude asks for confirmation before tool calls by default; destructive tools (deleting goals, funnels, sites) are marked so it always confirms those.


# Codex (/zh/docs/mcp/codex)



Connecting Codex to Rybbit lets it check analytics as part of your development workflow — verifying that a fixed error stopped occurring, checking which routes get traffic before a refactor, or creating goals and funnels for features as you ship them.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

The simplest way to connect — add the server and log in:

```bash
codex mcp add rybbit --url https://app.rybbit.io/api/mcp
codex mcp login rybbit
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

`codex mcp login` opens your browser to log in to Rybbit and approve access; the connection acts with your user's role.

## Connect with an API key [#connect-with-an-api-key]

Use an [API key](/docs/mcp#1-create-an-api-key) instead for non-interactive runs or a narrower, scoped credential. Register the name of an environment variable holding the key:

```bash
codex mcp add rybbit --url https://app.rybbit.io/api/mcp \
  --bearer-token-env-var RYBBIT_API_KEY
```

Codex reads the key from that variable rather than storing it, so `RYBBIT_API_KEY` must be exported in the shell that launches Codex. Equivalently, configure it in `~/.codex/config.toml`:

```toml
[mcp_servers.rybbit]
url = "https://app.rybbit.io/api/mcp"
bearer_token_env_var = "RYBBIT_API_KEY"
```

## Verify [#verify]

Run `codex mcp list` (or `/mcp` inside the Codex TUI) to confirm the server is connected, then try:

> List my Rybbit sites and summarize last week's traffic for each.


# Cursor (/zh/docs/mcp/cursor)



Connecting Cursor to Rybbit lets its agent check analytics while you code — confirming an error fix landed in production, checking traffic to a route before deleting it, or setting up goals and funnels for a new feature.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Add the server [#add-the-server]

1. [Create an API key](/docs/mcp#1-create-an-api-key) in Rybbit.
2. Add the server to `~/.cursor/mcp.json` (global — available in all projects) or `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "rybbit": {
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer <RYBBIT_API_KEY>"
      }
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Prefer the global file for a personal key. If you configure the server in a project's `.cursor/mcp.json`, don't commit the key — give each developer their own, ideally [scoped](/docs/mcp#1-create-an-api-key) to what the agent needs.

## Verify [#verify]

Open **Cursor Settings → MCP**: the server should show as connected with its tool list, and can be toggled on and off there. Then ask the agent:

> List my Rybbit sites and summarize last week's traffic for each.


# MCP (/zh/docs/mcp)





Rybbit includes a hosted [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) endpoint. It gives an AI assistant read and write access to your analytics: exploring traffic and behavior data, and managing sites, goals, funnels, organization members, teams, and user profiles — through the same API the dashboard uses, with the same access checks, roles, and rate limits.

Your MCP client connects to Rybbit over HTTPS and sends your API key with each protocol request. Rybbit verifies the key before processing any message, and every tool call is authorized against the key user's role and site access.

## Connect a client [#connect-a-client]

If your client supports the MCP authorization flow — Claude Code, Codex, Claude Desktop, and opencode all do — you can [connect with OAuth](#or-connect-with-oauth) and skip API keys entirely. The steps below describe the API-key path, which works in every client and supports scoped credentials.

### 1. Create an API key [#1-create-an-api-key]

1. Open **Settings → Account** in Rybbit.
2. Create a key in the **Personal API Keys** section.
3. Copy it immediately. Rybbit only shows a new key once.

A key created without permissions can do everything its user can do. To hand an agent a narrower credential, create the key with scoped permissions (`POST /api/user/api-keys` with a `permissions` object, e.g. `{"analytics": ["read"], "goals": ["read", "write"]}`): the MCP tool list and every API call are then limited to those `resource:action` scopes. `write` implies `read` on the same resource, and scopes never elevate — org admin/owner requirements still apply. Deleting the key revokes the connection.

### 2. Add the endpoint [#2-add-the-endpoint]

Use this Streamable HTTP URL for Rybbit Cloud:

```text
https://app.rybbit.io/api/mcp
```

For a self-hosted installation, replace the host with your configured `BASE_URL`:

```text
https://analytics.example.com/api/mcp
```

Configure your client to send this header on every request:

```text
Authorization: Bearer <RYBBIT_API_KEY>
```

MCP clients use different configuration formats. A typical remote-server configuration has this shape:

```json
{
  "mcpServers": {
    "rybbit": {
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer <RYBBIT_API_KEY>"
      }
    }
  }
}
```

Use your client's secret or environment-variable support when available instead of saving the key in a file. Query-string API keys are not accepted by the MCP endpoint. Per-client walkthroughs — Claude Code, Codex, Claude Desktop, Cursor, VS Code, opencode — are in [Client guides](#client-guides) below.

### Or connect with OAuth [#or-connect-with-oauth]

Clients that support the MCP authorization flow can skip API keys entirely: add the endpoint URL with no headers, and the client discovers Rybbit's authorization server through the standard well-known metadata (`/.well-known/oauth-protected-resource`), registers itself, and opens a browser window for you to log in and approve access. The resulting access token acts with your user's role, exactly like an API key would.

OAuth grants support the same `resource:action` scopes as API keys (advertised in `scopes_supported`). A grant that requests only the standard OIDC scopes is unrestricted; a grant that requests custom scopes like `analytics:read` is limited to them. The requesting client controls which scopes it asks for — consent is currently approve-or-deny as a whole.

### 3. Start with context [#3-start-with-context]

Ask the assistant to call `list_sites`, or prompt it with something like:

> List my Rybbit sites, summarize last month's traffic for the docs site, and create a goal for signups.

`list_sites` returns the numeric `site_id` and `organization_id` required by the other tools, plus the key's role in each organization. It does not return API keys or member email addresses.

## Client guides [#client-guides]

Coding agents can use the endpoint to pull analytics into your development workflow — checking whether an error you just fixed still occurs in production, or looking up which pages matter before a refactor — and chat clients like Claude Desktop turn it into a conversational analytics interface. Follow the guide for your client:

<Cards>
  <Card icon="<SiClaude />" title="Claude Code" description="One command with OAuth or an API key, plus a no-secrets team setup" href="/docs/mcp/claude-code" />

  <Card title="Codex" description="codex mcp add, then OAuth login or a key from the environment" href="/docs/mcp/codex" />

  <Card icon="<SiClaude />" title="Claude Desktop" description="Add a custom connector on claude.ai, desktop, and mobile" href="/docs/mcp/claude-desktop" />

  <Card title="Cursor" description="mcp.json with an API key header" href="/docs/mcp/cursor" />

  <Card title="VS Code" description="Copilot agent mode, with the key kept out of the config file" href="/docs/mcp/vscode" />

  <Card title="opencode" description="Remote server config with OAuth login or env-based headers" href="/docs/mcp/opencode" />
</Cards>

Any other MCP client that supports Streamable HTTP works with the generic configuration from [step 2](#2-add-the-endpoint).

## Available tools [#available-tools]

### Analytics (read) [#analytics-read]

| Tool                      | Returns                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `get_overview`            | Sessions, pageviews, users, pages per session, bounce rate, and session duration       |
| `get_overview_timeseries` | The overview KPIs bucketed over time                                                   |
| `get_breakdown`           | Sessions broken down by one dimension (pages, referrers, countries, devices, UTM, ...) |
| `get_live_stats`          | Visitors active on the site right now                                                  |
| `get_event_names`         | Custom event names tracked on the site with counts                                     |
| `get_errors`              | JavaScript errors grouped by name/message with occurrence counts                       |
| `get_web_vitals`          | Core Web Vitals percentiles (LCP, CLS, INP, FCP, TTFB)                                 |
| `get_retention`           | User retention cohort table                                                            |
| `get_journeys`            | Most common page-to-page navigation paths                                              |
| `get_annotations`         | Notes pinned to dates on the traffic chart (launches, deploys, campaigns, outages)     |
| `list_segments`           | Saved segments: named, reusable filter sets for a site or the whole organization       |
| `apply_segment`           | Overview KPIs for visitors matching a saved segment, with its filters for reuse        |

### Sites [#sites]

| Tool                 | Does                                                                                   |
| -------------------- | -------------------------------------------------------------------------------------- |
| `list_sites`         | List organizations and sites the key can access (call this first)                      |
| `get_site`           | One site's full configuration                                                          |
| `create_site`        | Add a new site to an organization &#x2A;(admin)*                                       |
| `update_site_config` | Change site settings: name, domain, tracking features, exclusions, tags &#x2A;(admin)* |
| `delete_site`        | Permanently delete a site and its data &#x2A;(admin, destructive)*                     |

### Goals & funnels [#goals--funnels]

| Tool             | Does                                                   |
| ---------------- | ------------------------------------------------------ |
| `get_goals`      | Conversion goals with conversion stats                 |
| `create_goal`    | Create a path, event, or autocapture goal              |
| `update_goal`    | Replace a goal's definition                            |
| `delete_goal`    | Permanently delete a goal &#x2A;(destructive)*         |
| `get_funnels`    | Saved funnel definitions                               |
| `analyze_funnel` | Compute an ad-hoc funnel without saving it             |
| `save_funnel`    | Save a funnel, or update one by passing `funnel_id`    |
| `delete_funnel`  | Permanently delete a saved funnel &#x2A;(destructive)* |

### People [#people]

| Tool                 | Does                                                                        |
| -------------------- | --------------------------------------------------------------------------- |
| `get_users`          | Person inventory with per-user aggregates and traits (sortable, searchable) |
| `get_user`           | One person's profile: traits, linked devices, vitals, locations             |
| `identify_user`      | Link an anonymous device to your user ID and merge traits                   |
| `update_user_traits` | Replace a person's traits wholesale                                         |
| `delete_user`        | GDPR erasure of one person's analytics data &#x2A;(admin, destructive)*     |

### Organization & teams [#organization--teams]

| Tool                        | Does                                                           |
| --------------------------- | -------------------------------------------------------------- |
| `list_members`              | Organization members with roles, site access, and teams        |
| `add_member`                | Add an existing Rybbit user to the organization &#x2A;(admin)* |
| `update_member_site_access` | Restrict a member to specific sites &#x2A;(admin)*             |
| `list_teams`                | Teams with members and site access                             |
| `create_team`               | Create a team &#x2A;(admin)*                                   |
| `update_team`               | Rename a team or replace its members/sites &#x2A;(admin)*      |
| `delete_team`               | Permanently delete a team &#x2A;(admin, destructive)*          |

### Raw data & SQL [#raw-data--sql]

| Tool               | Does                                                                   |
| ------------------ | ---------------------------------------------------------------------- |
| `get_sessions`     | Recent visitor sessions with full attribution                          |
| `get_session`      | One session's detail plus its event timeline                           |
| `get_events`       | Raw recent events, newest first                                        |
| `get_query_schema` | The ClickHouse schema and rules for `run_query`                        |
| `run_query`        | Read-only ClickHouse SQL against the site-scoped `scoped_events` table |

Analytics tools accept optional time inputs (`start_date`/`end_date` with an IANA `time_zone`, or `past_minutes`) and the same filters as the dashboard. Omitting time inputs queries all time; an unrecognized `time_zone` is rejected before the call is made. `get_sessions`, `get_events`, and `get_users` accept an optional `fields` list to return only the named row columns, which keeps large result sets small.

## Permissions and roles [#permissions-and-roles]

The MCP surface mirrors the REST API's permission model:

* **Read tools** work for any member with access to the site.
* **Write tools** need at least member-level site access (goals, funnels, `identify_user`, `update_user_traits`, `save_funnel`).
* **Tools marked &#x2A;(admin)*** require the API key's user to hold the **admin or owner** role in the organization; `add_member` can grant the `owner` role only from an owner's key. The REST layer enforces all of this — an underprivileged key gets a 403 with an explanatory message.

To give an assistant a read-only or read-mostly view, create a **scoped** API key (see step 1): grant only the `resource:action` scopes it needs — e.g. `{"analytics": ["read"], "sessions": ["read"]}` for a reporting agent. The MCP tool list is filtered to those scopes, and any out-of-scope call returns `403 { "error": "Insufficient scope", "required": "goals:write" }`. Alternatively, connecting with a member-role user's key hides nothing but refuses every call requiring the admin/owner role.

OAuth clients request scopes through the standard grant. Rybbit advertises the same `resource:action` scopes in its discovery metadata; a grant carrying no custom scopes (or only the standard OIDC scopes) is treated as full access, for backward compatibility.

## Destructive tools [#destructive-tools]

`delete_goal`, `delete_funnel`, `delete_site`, `delete_team`, and `delete_user` permanently destroy data and are marked with the MCP `destructiveHint` annotation, so well-behaved clients ask for confirmation before invoking them. `delete_site` and `delete_user` (the GDPR-erasure path) also remove recorded events and replays, with erasure completing asynchronously.

## Data and security boundary [#data-and-security-boundary]

* The API key is verified before any MCP message is processed, and each tool call re-runs the corresponding REST route's own access checks, role requirements, and rate limits.
* The surface returns whatever the REST API returns for your role — including session-level records and, where a site has IP tracking enabled, visitor IP addresses. Connect only AI clients you trust with that data, and use a separate, revocable API key per integration.
* Text originating in tracked traffic (page titles, paths, referrers, event names, traits) is stripped of control and bidi-override characters. AI clients should still treat these values as untrusted data, never as instructions.
* `run_query` is restricted to a read-only, site-scoped table with row and execution-time caps.
* The server does not contain an AI model or send analytics to an AI provider. Data only leaves Rybbit in response to the MCP client you configure.
* The endpoint is stateless. Each HTTP request is independently authenticated.

## Troubleshooting [#troubleshooting]

* **401 Unauthorized:** The client did not send a Bearer credential, or the key/token is invalid, expired, or revoked. OAuth-capable clients re-authenticate automatically via the `WWW-Authenticate` challenge.
* **OAuth login loop or "table does not exist" (self-hosted):** Run `npm run db:push` in `server/` to create the OAuth tables, then retry.
* **403 in tool results:** The key's user lacks access to that site or organization — or the tool requires an org admin/owner role. Check the `role` field in `list_sites`.
* **403 "Insufficient scope":** The credential was created without the `resource:action` scope this tool needs (the `required` field names it). Use a key or OAuth grant that includes it.
* **429 Too Many Requests:** The API key exceeded its plan's rate limit.
* **503 Service Unavailable:** Rybbit could not verify the key. Retry the request; do not replace a known-valid key based on this response.
* **405 Method Not Allowed on GET:** This is expected. The stateless endpoint accepts MCP messages over `POST`.
* **Site access error:** Call `list_sites` again. Membership or site permissions may have changed.


# opencode (/zh/docs/mcp/opencode)



Connecting opencode to Rybbit lets it pull analytics into your terminal workflow — verifying an error fix in production, checking a route's traffic before removing it, or wiring up goals and funnels as you ship.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Connect with OAuth [#connect-with-oauth]

Add the server to `opencode.json` at your project root (or your global opencode config):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rybbit": {
      "type": "remote",
      "url": "https://app.rybbit.io/api/mcp",
      "enabled": true
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

Then authenticate:

```bash
opencode mcp auth rybbit
```

Your browser opens Rybbit's [OAuth flow](/docs/mcp#or-connect-with-oauth) — log in and approve access. The connection acts with your user's role, and the committed config carries no secret. `opencode mcp logout rybbit` removes the stored credential.

## Connect with an API key [#connect-with-an-api-key]

To use an [API key](/docs/mcp#1-create-an-api-key) instead — for non-interactive runs or a narrower, scoped credential — add a headers block that reads the key from the environment, so the config stays committable:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rybbit": {
      "type": "remote",
      "url": "https://app.rybbit.io/api/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:RYBBIT_API_KEY}"
      }
    }
  }
}
```

## Verify [#verify]

Run `opencode mcp list` to see the server and its authentication status (`opencode mcp debug rybbit` gives detailed diagnostics), then try:

> List my Rybbit sites and summarize last week's traffic for each.


# VS Code (/zh/docs/mcp/vscode)



Connecting VS Code to Rybbit gives Copilot's agent mode access to your analytics — checking whether a fixed error still occurs, looking up which pages matter before a refactor, or creating goals for a feature as you build it.

This page covers client setup only. The [MCP overview](/docs/mcp) covers the endpoint, API keys and scopes, the full tool list, and troubleshooting.

## Add the server [#add-the-server]

1. [Create an API key](/docs/mcp#1-create-an-api-key) in Rybbit.
2. Create `.vscode/mcp.json` in your workspace. The `inputs` block keeps the key out of the file — VS Code prompts for it once when the server first starts and stores it securely, so this file is safe to commit:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "rybbit-api-key",
      "description": "Rybbit API key",
      "password": true
    }
  ],
  "servers": {
    "rybbit": {
      "type": "http",
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:rybbit-api-key}"
      }
    }
  }
}
```

For a self-hosted installation, replace the host with your configured `BASE_URL`.

To make the server available in every workspace instead, run **MCP: Open User Configuration** from the Command Palette and add the same JSON there. **MCP: Add Server** offers a guided setup as an alternative to editing the file.

## Verify [#verify]

Run **MCP: List Servers** from the Command Palette — Rybbit should be listed with its tools, which also appear in the tools picker in Copilot's agent mode. Then ask the agent:

> List my Rybbit sites and summarize last week's traffic for each.


# Angular (/zh/docs/guides/angular)





An Angular CLI project serves one HTML shell, `src/index.html`, for every route. Paste the snippet into its `<head>` and the script loads once for the whole app.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Angular [#add-the-snippet-to-angular]

    Open `src/index.html` and paste the snippet just before `</head>`:

    ```html title="src/index.html"
    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>MyAngularApp</title>
      <base href="/">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
      <app-root></app-root>
    </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Navigation through the Angular Router is tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Declare `rybbit` on `window` once so TypeScript accepts the call, then call `window.rybbit.event()` from any component or service. Guard the call so a blocked script does not throw.

```typescript title="src/app/feature/feature.component.ts"
import { Component } from "@angular/core";

declare global {
  interface Window {
    rybbit?: {
      event: (eventName: string, eventData?: Record<string, any>) => void;
      pageview: () => void;
    };
  }
}

@Component({
  selector: "app-feature",
  template: `<button (click)="onFeatureClick()">Use Feature</button>`,
})
export class FeatureComponent {
  onFeatureClick(): void {
    if (window.rybbit) {
      window.rybbit.event("feature_used", { featureName: "Amazing Feature" });
    }
  }
}
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing after navigation**: this is rare. If it happens, subscribe to `Router.events`, filter for `NavigationEnd` and call `window.rybbit.pageview()`; test the default behaviour first.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ASP.NET Core (/zh/docs/guides/aspnet)





ASP.NET Core MVC and Razor Pages apps share one layout file, `_Layout.cshtml`, that wraps every view, so the snippet goes into its `<head>`. Keep the site ID in `appsettings.json` and inject `IConfiguration` into the layout so nothing is hard-coded.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ASP.NET Core [#add-the-snippet-to-aspnet-core]

    #### Configure the site ID [#configure-the-site-id]

    Add a `Rybbit` section to `appsettings.json`:

    ```json filename="appsettings.json"
    {
      "Rybbit": {
        "InstanceUrl": "https://app.rybbit.io",
        "SiteId": "YOUR_SITE_ID"
      }
    }
    ```

    To keep the ID out of source control or vary it per environment, leave `SiteId` empty in `appsettings.json` and set it in `appsettings.Production.json`, or as the environment variable `Rybbit__SiteId` (double underscore separates configuration sections).

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open the layout file:

    * Controllers with views: `Views/Shared/_Layout.cshtml`
    * Razor Pages: `Pages/Shared/_Layout.cshtml`

    Inject `IConfiguration` at the top and add the tag inside `<head>`:

    ```razor filename="Views/Shared/_Layout.cshtml"
    @inject IConfiguration Configuration
    @{
        var rybbitSiteId = Configuration["Rybbit:SiteId"];
        var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
    }
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>@ViewData["Title"] - MyApp</title>
        <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />

        @if (!string.IsNullOrEmpty(rybbitSiteId))
        {
            <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
        }
    </head>
    ```

    If `Microsoft.Extensions.Configuration` is not already imported in `_ViewImports.cshtml`, add `@using Microsoft.Extensions.Configuration` above the `@inject` line.

    The `@if` guard skips the tag when `SiteId` is empty, so development is not tracked unless you set the value there. If your app has more than one layout, add the tag to each, or move it into a partial view and render it with `<partial name="_Rybbit" />` from every layout.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: environment-specific files such as `appsettings.Development.json` override `appsettings.json`, so check which environment you are running (`ASPNETCORE_ENVIRONMENT`) and that the `Rybbit` section exists there or in the base file. Environment variables override both.
* **Content Security Policy**: if middleware adds a `Content-Security-Policy` header, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Response caching or output caching**: the tag is rendered server-side, so a cached response keeps whatever configuration was active when it was cached. Clear the cache after changing the site ID.
* **Self-hosted instance**: set `Rybbit:InstanceUrl` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Astro (/zh/docs/guides/astro)





Astro pages share a layout component that renders the `<html>` document. Add the snippet to the `<head>` of that layout and every page that uses it is tracked.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Astro [#add-the-snippet-to-astro]

    Open your shared layout, usually `src/layouts/Layout.astro`, and paste the snippet inside `<head>`. Add `is:inline` so Astro leaves the tag as-is instead of bundling it:

    ```astro title="src/layouts/Layout.astro"
    ---
    const { title } = Astro.props;
    ---
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title>{title}</title>
        <script is:inline src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <slot />
      </body>
    </html>
    ```

    If you do not use a shared layout, add the same tag to the `<head>` of each page in `src/pages/`. A layout is easier to maintain.

    Astro builds a multi-page site by default, so each navigation is a full page load and a new pageview. With [view transitions](https://docs.astro.build/en/guides/view-transitions/) enabled, client-side navigation is tracked automatically when the URL changes.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a client-side `<script>` in any `.astro` component, or from inside a framework island the same way you would in that framework.

```astro title="src/components/TrackedButton.astro"
<button id="tracked-button">Click me</button>

<script>
  document.getElementById("tracked-button")?.addEventListener("click", () => {
    if (window.rybbit) {
      window.rybbit.event("astro_button_click", { source: "TrackedButton.astro" });
    }
  });
</script>
```

## Troubleshooting [#troubleshooting]

* **Pageviews missing with view transitions**: this is rare. If it happens, listen for Astro's `astro:after-swap` event in a client-side script and call `window.rybbit.pageview()`; test the default behaviour first.
* **Proxying through your own domain**: Astro can serve the script from your domain with SSR middleware. See the [Astro proxy guide](/docs/proxy-guide/astro).

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# BigCommerce (/zh/docs/guides/bigcommerce)





BigCommerce's **Script Manager** adds scripts to every storefront page without theme edits, and it is also where the order-confirmation purchase event goes. Editing the theme's `head.html` works too.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to BigCommerce [#add-the-snippet-to-bigcommerce]

    <Tabs items="[&#x22;Script Manager&#x22;, &#x22;Theme files&#x22;]">
      <Tab>
        1. In the control panel, go to **Storefront > Script Manager** and click **Create a Script**.
        2. Fill in the settings:
           * **Name**: Rybbit Analytics
           * **Placement**: Head
           * **Location**: All pages
           * **Script category**: Analytics
           * **Script type**: Script
        3. Paste the snippet into **Script contents** and click **Save**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Back up your theme before editing files.
        </Callout>

        1. Go to **Storefront > Themes**, click **Advanced** on your current theme, then **Edit Theme Files**.
        2. Open **templates > components > common** and then `head.html`.
        3. Paste the snippet at the end of the file, before the closing `</head>` tag, and click **Save**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Create a second script in Script Manager with **Placement: Footer**, **Location: Order Confirmation** and **Script type: Script**. BigCommerce runs Script Manager contents through Handlebars, so expressions such as `checkout.order.id` are filled in with the order data before the page is served:

```html
<script>
(function () {
  function waitForRybbit(callback, timeout) {
    var start = Date.now();
    (function check() {
      if (window.rybbit && typeof window.rybbit.event === 'function') {
        callback();
      } else if (Date.now() - start < timeout) {
        setTimeout(check, 100);
      }
    })();
  }

  waitForRybbit(function () {
    {{#if checkout.order}}
    window.rybbit.event('purchase', {
      transaction_id: '{{checkout.order.id}}',
      value: {{checkout.subtotal.value}},
      currency: '{{checkout.currency.code}}'
    });
    {{/if}}
  }, 5000);
})();
</script>
```

`waitForRybbit` polls until the tracking script from the head has defined `window.rybbit`, so the event is not lost if the confirmation page runs the footer script first.

## Troubleshooting [#troubleshooting]

* **Script not on the page**: confirm the script is enabled in Script Manager, then purge the store cache under **Server Settings > Store-level caching > Purge cache**.
* **Purchase event missing**: the purchase script must use the **Order Confirmation** location, and the `checkout.order`, `checkout.subtotal` and `checkout.currency` Handlebars objects depend on your BigCommerce checkout version. Place a test order to confirm the event arrives.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Blazor (/zh/docs/guides/blazor)





Where the snippet goes depends on the Blazor hosting model: a Blazor Web App keeps its `<head>` in `Components/App.razor`, a standalone Blazor WebAssembly app in `wwwroot/index.html`, and a Blazor Server app (.NET 7 and earlier) in `Pages/_Host.cshtml`. In each case the tag is added once and stays on the page while Blazor handles navigation client-side.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Blazor [#add-the-snippet-to-blazor]

    <Tabs items="[&#x22;Blazor Web App&#x22;, &#x22;Blazor WebAssembly (standalone)&#x22;, &#x22;Blazor Server (.NET 7 and earlier)&#x22;]">
      <Tab>
        `App.razor` is rendered on the server, so it can read the site ID from `appsettings.json`. Add a `Rybbit` section:

        ```json filename="appsettings.json"
        {
          "Rybbit": {
            "InstanceUrl": "https://app.rybbit.io",
            "SiteId": "YOUR_SITE_ID"
          }
        }
        ```

        Then inject `IConfiguration` in `Components/App.razor` and add the tag inside `<head>`:

        ```razor filename="Components/App.razor"
        @inject IConfiguration Configuration
        @{
            var rybbitSiteId = Configuration["Rybbit:SiteId"];
            var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
        }
        <!DOCTYPE html>
        <html lang="en">

        <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <base href="/" />
            <link rel="stylesheet" href="@Assets["app.css"]" />
            <HeadOutlet />

            @if (!string.IsNullOrEmpty(rybbitSiteId))
            {
                <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
            }
        </head>
        ```

        Override the value per environment with `appsettings.Production.json` or the environment variable `Rybbit__SiteId`.
      </Tab>

      <Tab>
        A standalone WebAssembly app ships `wwwroot/index.html` as a static file, so add the tag directly inside `<head>`:

        ```html filename="wwwroot/index.html"
        <head>
            <base href="/" />
            <link rel="stylesheet" href="css/app.css" />

            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        The site ID is public on every platform (it is in the page source), so a static value here is fine; `wwwroot/appsettings.json` is equally visible to the browser and offers no advantage for this value.
      </Tab>

      <Tab>
        Add the `Rybbit` section to `appsettings.json` as in the Blazor Web App tab, then open `Pages/_Host.cshtml` (or `Pages/_Layout.cshtml` in .NET 6 projects, where the `<head>` lives) and add the tag:

        ```razor filename="Pages/_Host.cshtml"
        @page "/"
        @using Microsoft.Extensions.Configuration
        @inject IConfiguration Configuration
        @{
            var rybbitSiteId = Configuration["Rybbit:SiteId"];
            var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";
        }
        <!DOCTYPE html>
        <html lang="en">
        <head>
            <base href="~/" />
            <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

            @if (!string.IsNullOrEmpty(rybbitSiteId))
            {
                <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>
            }
        </head>
        ```
      </Tab>
    </Tabs>

    #### Navigation [#navigation]

    Blazor's router, `NavigationManager.NavigateTo` and enhanced navigation in Blazor Web Apps all update the URL through `history.pushState` (or `replaceState` when `replace: true`) rather than reloading the page. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). Enhanced navigation patches the DOM without re-running scripts already in `<head>`, which is what you want: the tracker loads once and keeps running. `NavigateTo(url, forceLoad: true)` and links with `data-enhance-nav="false"` do a full page load, which the script tracks as a new pageview.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in a Blazor Web App**: `App.razor` reads server-side configuration, so check the `appsettings` file for the active `ASPNETCORE_ENVIRONMENT`; environment variables override the files.
* **Blazor WebAssembly PWA**: `index.html` is cached by the service worker. Users receive the new tag only after the app is republished and the service worker updates.
* **Content Security Policy**: if you set one, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `Rybbit:InstanceUrl` (or the static URL in `index.html`) to your own domain without a trailing slash.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Bolt (/zh/docs/guides/bolt)





Bolt has no settings field for custom head code (its **Analytics** project setting only shows traffic for published sites), so the snippet goes into the app's HTML head as a code change: prompt Bolt to add it, or switch to Code view and paste it into the root HTML or layout file. Publish the project again afterwards.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Bolt [#add-the-snippet-to-bolt]

    <Tabs items="[&#x22;Ask Bolt&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of every page and keep all existing head tags:
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Review the change Bolt makes before you move on: the tag should be in the document head, not inside a component.
      </Tab>

      <Tab>
        Click the **Code Preview** icon (`<>`) at the top center to switch to Code view, then open the file that owns the `<head>` for the framework Bolt chose:

        * **Vite** projects (React, Vue, Svelte): `index.html` at the project root.
        * **Next.js** projects: `app/layout.tsx`, using the `next/script` component as in the [Next.js guide](/docs/guides/react/next-js).
        * Any other framework: ask Bolt "which file renders the HTML head?" and edit that one.

        For a Vite project, paste the snippet before `</head>`:

        ```html title="index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Click **Save** or press **Ctrl+S**.
      </Tab>
    </Tabs>

    Publish the change: open the **Publish** menu and click **Publish** the first time, or **Update** for a site that is already live. In-app navigation is tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Published site unchanged**: edits are not applied to the live site until you click **Update** in the **Publish** menu.
* **Bolt removed the tag**: later prompts can regenerate `index.html` or the layout. Right-click the file in the **Files** list and choose **Lock file** so Bolt leaves it alone, or add a line to the project's **Knowledge** telling it to keep the Rybbit script.
* **Expo (mobile) projects**: a script tag only runs in the web build. For the native app, use the [JavaScript SDK](/docs/sdks/web) instead.
* **Numbers differ from Bolt's Analytics**: Bolt's built-in counts include crawlers and bots; Rybbit filters them.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Bubble.io (/zh/docs/guides/bubble)





Bubble adds custom header code to every page of your app through the **SEO / metatags** settings tab, so the snippet goes there once and ships with your next deploy.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Bubble.io [#add-the-snippet-to-bubbleio]

    1. Open your app in the Bubble editor and click the **Settings** tab in the left sidebar.
    2. Open the **SEO / metatags** sub-tab.
    3. Scroll to **Script/meta tags in header** and paste the snippet. It is added to the `<head>` of every page in the app.
    4. Deploy the app to **Live**. The development version does not pick up the change until you deploy.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Bubble workflows can run arbitrary JavaScript through a **Run JavaScript** action (provided by the free Toolbox plugin). Use it to send events from any workflow trigger.

1. Open the **Workflow** tab and pick the trigger, for example *When Button Signup is clicked*.
2. Add a **Run JavaScript** action.
3. Paste the call, using Bubble's dynamic expressions for the values:

```javascript
if (window.rybbit) {
  window.rybbit.event("signup_clicked", {
    plan: "Current User's Plan",
  });
}
```

## Troubleshooting [#troubleshooting]

* **Only the first pageview is tracked**: Bubble apps that switch between groups on a single page do not change the URL, so there is nothing for the script to detect. Add a **Run JavaScript** action that calls `window.rybbit.pageview()` when the group becomes visible, or track those views as custom events. Apps that navigate between real Bubble pages are tracked automatically.
* **Snippet missing on the live site**: the header script is versioned with your app, so check that you deployed to Live after saving the setting.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Capacitor (/zh/docs/guides/capacitor)





Capacitor wraps a normal web app in a native WebView, so the snippet goes in the `<head>` of that web app's `index.html` and ships to iOS and Android with `npx cap sync`. If the app is built with Ionic Angular, React or Vue, follow the [Angular](/docs/guides/angular), [React](/docs/guides/react/vite-cra) or [Vue](/docs/guides/vue/vite) guide for where the tag lives, then come back here for the WebView origin settings.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Capacitor [#add-the-snippet-to-capacitor]

    1. Paste the snippet into the `<head>` of your web app's `index.html` (the file in the `webDir` folder from `capacitor.config`, after your framework's build):

    ```html title="index.html"
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    2. Enable `CapacitorHttp`, which routes `window.fetch` through native HTTP. The iOS WebView runs on `capacitor://localhost`, and Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so without this the browser blocks the requests on iOS:

    ```ts title="capacitor.config.ts"
    import type { CapacitorConfig } from "@capacitor/cli";

    const config: CapacitorConfig = {
      appId: "com.example.app",
      appName: "My App",
      webDir: "dist",
      plugins: {
        CapacitorHttp: {
          enabled: true,
        },
      },
    };

    export default config;
    ```

    3. Build the web app, then copy it into the native projects:

    ```bash
    npm run build
    npx cap sync
    ```

    Android serves the app from `https://localhost` (`server.androidScheme` defaults to `https`), which is a regular origin, so tracking works there with or without `CapacitorHttp`. In-app route changes are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.

    <Callout type="info">
      Use the script tag rather than the `@rybbit/js` npm package on Capacitor. The package sends events with `navigator.sendBeacon`, which `CapacitorHttp` does not patch, so its requests from `capacitor://localhost` are still blocked on iOS.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Works on Android and in the browser, silent on iOS**: `CapacitorHttp` is not enabled, or the native projects were not re-synced after changing the config. Run `npx cap sync` and rebuild in Xcode.
* **Changes do not appear on device**: `npx cap sync` copies the built web bundle; edit the source, rebuild the web app, then sync again.
* **Live reload during development**: with `server.url` pointing at your dev server the WebView loads an `http://` origin, so requests succeed even without `CapacitorHttp`. Do not read a working dev build as proof that the production build is configured.
* **Every pageview shows `localhost` as hostname**: expected. `server.hostname` defaults to `localhost` on both platforms; filter by site, not hostname.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Carrd (/zh/docs/guides/carrd)





Carrd builds one-page sites, and the snippet goes into the **Head** embed code field in the site settings.

<Callout type="warn">
  Custom head code requires a **Carrd Pro** subscription (Pro Standard or Pro Plus). The Embed Code feature is not included on Pro Lite.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Carrd [#add-the-snippet-to-carrd]

    1. Open your site in the Carrd editor and click the **Settings** gear in the top right.
    2. Open the **Settings** tab and scroll to **Embed Code**.
    3. Paste the following into the **Head** field:

    ```html
    <script>
      (function () {
        var s = document.createElement("script");
        s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
        s.defer = true;
        document.head.appendChild(s);
      })();
    </script>
    ```

    This wraps the snippet in a small loader so Carrd's embed processing cannot rewrite the tag.

    4. Click **Save**, then **Publish**. Changes are not live until you publish.

    If your site has multiple pages (a Pro Plus feature), the head code loads on all of them.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **The Head field is missing**: the site is on Pro Lite or the free plan. Upgrade to Pro Standard or Pro Plus.
* **Snippet not in the page source**: the site was saved but not published. Publish again from the editor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Chrome extension (/zh/docs/guides/chrome-extension)





Manifest V3 requires every piece of executable code to ship inside the extension package, and the `extension_pages` Content Security Policy is fixed at `script-src 'self' 'wasm-unsafe-eval'; object-src 'self'` with no way to relax it. A remote `<script>` tag can therefore never load in an extension page. Bundle the `@rybbit/js` SDK into your popup, options or side panel page instead, and grant `host_permissions` for the analytics host.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.

    You only need the site ID from the snippet; the script tag itself is not used in an extension.
  </Step>

  <Step>
    ### Add the snippet to Chrome extension [#add-the-snippet-to-chrome-extension]

    1. Install the SDK in the extension project:

    ```bash
    npm install @rybbit/js
    ```

    2. Initialise it in the entry script of each extension page you want to track (the popup from `action.default_popup`, the options page from `options_ui.page`, the side panel from `side_panel.default_path`). The SDK needs `window` and `document`, so do not import it in the service worker.

    ```js title="src/popup.js"
    import rybbit from "@rybbit/js";

    await rybbit.init({
      analyticsHost: "https://app.rybbit.io/api",
      siteId: "YOUR_SITE_ID",
    });

    // Extension pages have URLs like chrome-extension://<id>/popup.html.
    // Report a readable path instead:
    rybbit.pageview("/popup");
    ```

    3. Grant the extension permission to call the analytics host. Requests from extension pages to origins listed in `host_permissions` are not subject to CORS:

    ```json title="manifest.json"
    {
      "manifest_version": 3,
      "host_permissions": ["https://app.rybbit.io/*"]
    }
    ```

    4. Build the extension with your bundler (Vite, webpack, Rollup) so `@rybbit/js` ends up inside the package, then reload the unpacked extension at `chrome://extensions`.

    The default extension CSP does not restrict `connect-src`, so no `content_security_policy` entry is required. If you define your own policy, add `https://app.rybbit.io` to its `connect-src`.

    <Callout type="warn">
      Do not initialise the SDK in a content script. Content scripts run inside third-party websites; tracking there records other people's pages under your site ID, and content scripts are subject to the host page's same-origin policy in any case.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `rybbit.event()` from the page script, or use data attributes on buttons in your popup HTML:

```js title="src/popup.js"
document.getElementById("save")?.addEventListener("click", () => {
  rybbit.event("settings_saved", { theme: "dark" });
});
```

```html title="popup.html"
<button data-rybbit-event="upgrade_click" data-rybbit-prop-plan="pro">Upgrade</button>
```

## Troubleshooting [#troubleshooting]

* **`Refused to load the script` in the popup console**: the fixed `extension_pages` CSP blocked a remote tag. Remove it and use the SDK.
* **`POST /api/track` blocked by CORS**: `host_permissions` is missing or does not match. The pattern must include the path wildcard: `https://app.rybbit.io/*`.
* **Self-hosted Rybbit**: replace `https://app.rybbit.io` in both `analyticsHost` and `host_permissions` with your own instance URL.
* **Every pageview shows the extension ID as hostname**: expected. Extension pages live on `chrome-extension://<id>`; use `rybbit.pageview("/name")` for readable paths.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Circle (/zh/docs/guides/circle)





Circle has a **Code snippets** setting that injects custom code into the `<head>` of every page in your community, so the snippet goes there once and covers public pages and logged-in member pages alike.

<Callout type="info">
  Custom CSS/JavaScript snippets are included on all current Circle plans (Professional, Business and Circle Plus).
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Circle [#add-the-snippet-to-circle]

    1. Open your community as an admin and go to **Settings**.
    2. Open **Code snippets**.
    3. Paste the snippet into the **Head code snippets** field.
    4. Click **Save**. Changes apply to the whole community immediately; there is no publish step.

    Circle's own help article for this setting is [Custom code snippets](https://help.circle.so/p/administration/site-management/custom-code-snippets).

    Circle is a single-page app: after the first load, navigating between spaces, posts and courses changes the URL without a full reload. The script tracks these client-side route changes automatically, so each space and post shows up as its own pageview.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Custom domain**: the same head code is served on `yourcommunity.circle.so` and on your custom domain. If both hostnames are in use, keep them under one site in Rybbit so sessions are not split.
* **Post embeds**: custom HTML embedded inside a post is scoped to that post. Put the snippet in head code snippets, not in a post.
* **Nothing tracked while logged in as admin**: Circle applies head code to admins too, so check that your own IP or user is not excluded in Rybbit's site settings before assuming the snippet is missing.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ClickFunnels (/zh/docs/guides/clickfunnels)





ClickFunnels 2.0 has a **Header Code** field at three levels: **Site Settings** for the whole workspace, **Funnel settings** for every page in one funnel, and the page editor for a single page. Add the snippet at the widest level you want tracked and leave the narrower ones empty so it is not loaded twice.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ClickFunnels [#add-the-snippet-to-clickfunnels]

    <Tabs items="[&#x22;Whole site&#x22;, &#x22;One funnel&#x22;, &#x22;One page&#x22;]">
      <Tab>
        1. In your workspace, open the **Site & Blog** app in the left menu and click **Site Settings**.
        2. Paste the snippet into **Header Code**.
        3. Save.

        This applies to every page in the workspace: funnel pages, store pages, courses, blog posts and site pages.
      </Tab>

      <Tab>
        1. Open **Funnels** and click the **Settings** gear next to the funnel (or the **Settings** button in the top-right of the funnel workflow editor).
        2. Paste the snippet into **Head Code**.
        3. Click **Update Funnel**.

        The code loads on every page of that funnel only.
      </Tab>

      <Tab>
        1. Open the page in the page editor.
        2. Go to **Settings > Tracking Code** and paste the snippet into **Header Code**.
        3. Click **Save**.

        The code loads on this page only.
      </Tab>
    </Tabs>

    Save, then open the live page URL to test: header code does not run inside the page editor.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Duplicate pageviews**: the snippet is present at more than one level (site and funnel, or funnel and page). Keep a single copy.
* **Snippet not in the page source**: check which level you pasted it at. Site Settings covers the workspace, funnel settings cover that funnel's pages only, and the page editor covers one page.
* **jQuery**: ClickFunnels pages already include jQuery, so do not load it again in the same header code block; a second copy can break page scripts.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Contentful (/zh/docs/guides/contentful)





Contentful is a headless CMS: it stores content and delivers it over its APIs, but never renders your pages. The tracking snippet therefore goes into the frontend that consumes Contentful, not into Contentful itself.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Contentful [#add-the-snippet-to-contentful]

    <Callout type="info">
      Contentful has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Contentful.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Contentful frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby), which pairs with the official `gatsby-source-contentful` plugin
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Editor previews count as visits**: Contentful's content preview URLs open a preview or draft build of your frontend. Register that deployment as a separate site in Rybbit, or leave the snippet out of preview builds, so editors' previews are not mixed into your production data.
* **The Contentful web app is not tracked**: the snippet only runs on your frontend, so time spent editing in Contentful never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Craft CMS (/zh/docs/guides/craft-cms)





Craft CMS renders pages from Twig templates in the `templates/` folder, so the snippet goes into the base template that your section templates extend. A fresh `craftcms/craft` project ships a single `templates/index.twig` containing the full HTML document; most projects move that boilerplate into a base template and `{% extends %}` it.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Craft CMS [#add-the-snippet-to-craft-cms]

    1. Open the template that owns your `<head>`. In a fresh install that is `templates/index.twig`; in a project with a base template it is the underscore-prefixed file every page extends, such as `templates/_layout.twig`.
    2. Add the tag before `</head>`:

    ```twig title="templates/_layout.twig"
    <!DOCTYPE html>
    <html lang="{{ currentSite.language }}">
    <head>
        <meta charset="utf-8">
        <title>{{ siteName }}</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        {% block content %}{% endblock %}
    </body>
    </html>
    ```

    3. Every section template that extends the base template now loads the script:

    ```twig title="templates/blog/_entry.twig"
    {% extends "_layout" %}

    {% block content %}
        <h1>{{ entry.title }}</h1>
        {{ entry.body }}
    {% endblock %}
    {% endraw %}
    ```

    To keep the site ID out of templates and vary it per environment, read it from `.env` with `{{ getenv('RYBBIT_SITE_ID') }}`, or store it in a Global Set and use `{{ settings.rybbitSiteId }}`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Template caching**: if you wrap the head in `{% cache %}` tags, the change appears only after the cache expires or you run `php craft clear-caches/all`.
* **Live Preview counts as visits**: the control panel's Live Preview renders your template in an iframe with `x-craft-live-preview` in the query string. Wrap the tag in `{% if not craft.app.request.isPreview %}` to leave editors' previews out of your data.
* **Control panel is not tracked**: `/admin` uses Craft's own templates, so the snippet never runs there.
* **Multiple base templates**: if some sections extend a different base (for example `_layout-landing.twig`), add the tag to each one, or move it into a partial and `{% include %}` it from every base.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Discourse (/zh/docs/guides/discourse)





Discourse adds site-wide code through **theme components**. A component has an editable `</head>` section that Discourse injects into every page and, because Discourse ships a strict Content Security Policy, it stamps the required nonce onto script tags placed there. No server access or plugin is needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Discourse [#add-the-snippet-to-discourse]

    1. In the admin sidebar open **Appearance → Themes and components** (older versions: **Admin → Customize → Themes**).
    2. On the **Components** tab click **Install**, choose **Create new**, name it "Rybbit Analytics", make sure the type is **Component** and click **Create**.
    3. Click **Edit CSS/HTML**, stay on the **Common*&#x2A; tab and open the &#x2A;*`</head>`** section (not **Header**, which is the visible page header).
    4. Paste the snippet and click **Save**.
    5. Back on the component page, add your active theme under **Include component on these themes** so the component is enabled.

    Discourse is a single-page app: after the first load, topics and categories open without a full page reload. The tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`, so those navigations are recorded as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Component saved but the script is missing from the page source**: the component is not attached to the active theme. Add the theme under **Include component on these themes**, or add the component from the theme's **Included components** list.
* **Script tag present but blocked**: check the browser console for a CSP error. Scripts added through the `</head>` section receive Discourse's nonce automatically; scripts injected any other way (for example from a plugin's raw HTML) do not.
* **Only the first pageview is recorded**: the **SPA Navigation** setting is off for the site in your Rybbit dashboard. Turn it on under Site Settings.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Django (/zh/docs/guides/django)





Django pages extend a base template, so the snippet goes into the `<head>` of that base template. Put the site ID in `settings.py`, read from an environment variable, and pass it to templates with a small context processor so no template hard-codes the ID.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Django [#add-the-snippet-to-django]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to `settings.py`, reading from the environment:

    ```python filename="settings.py"
    import os

    RYBBIT_INSTANCE_URL = os.environ.get("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
    RYBBIT_SITE_ID = os.environ.get("RYBBIT_SITE_ID", "")
    ```

    Set `RYBBIT_SITE_ID=YOUR_SITE_ID` in your production environment (or your `.env` file if you load one with django-environ or python-dotenv).

    #### Expose the values to templates [#expose-the-values-to-templates]

    Create a context processor that adds both settings to every template context:

    ```python filename="myproject/context_processors.py"
    from django.conf import settings


    def rybbit(request):
        return {
            "RYBBIT_INSTANCE_URL": settings.RYBBIT_INSTANCE_URL,
            "RYBBIT_SITE_ID": settings.RYBBIT_SITE_ID,
        }
    ```

    Register it under `TEMPLATES` in `settings.py`:

    ```python filename="settings.py"
    TEMPLATES = [
        {
            "BACKEND": "django.template.backends.django.DjangoTemplates",
            "DIRS": [BASE_DIR / "templates"],
            "APP_DIRS": True,
            "OPTIONS": {
                "context_processors": [
                    "django.template.context_processors.request",
                    "django.contrib.auth.context_processors.auth",
                    "django.contrib.messages.context_processors.messages",
                    "myproject.context_processors.rybbit",
                ],
            },
        },
    ]
    ```

    #### Add the tag to your base template [#add-the-tag-to-your-base-template]

    Open the template that every page extends, usually `templates/base.html`, and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My Site{% endblock %}</title>

        {% if RYBBIT_SITE_ID %}
        <script src="{{ RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ RYBBIT_SITE_ID }}" defer></script>
        {% endif %}
    </head>
    ```

    The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable.

    Pages that do not `{% extends "base.html" %}` (for example a separate admin or landing template) need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: settings are read at startup, so restart the server (or your WSGI/ASGI workers) after changing `RYBBIT_SITE_ID`. Confirm the context processor path matches your project package name.
* **Template rendered without a request**: context processors only run for templates rendered with a `RequestContext`, which `render()` and class-based views provide. `Template.render()` without a request has no `RYBBIT_SITE_ID` and the guard hides the tag.
* **Content Security Policy**: if you use django-csp, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Docusaurus (/zh/docs/guides/docusaurus)





Docusaurus has a `scripts` option in `docusaurus.config.js` that adds a `<script>` tag to the `<head>` of every page, so no theme swizzling is needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Docusaurus [#add-the-snippet-to-docusaurus]

    Open `docusaurus.config.js` (or `docusaurus.config.ts`) at the root of your project and add the script to the `scripts` array:

    ```javascript filename="docusaurus.config.js"
    /** @type {import('@docusaurus/types').Config} */
    const config = {
      // ... title, url, baseUrl, presets, themeConfig

      scripts: [
        {
          src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
          defer: true,
        },
      ],
    };

    module.exports = config;
    ```

    If you already manage tags through `headTags`, this form is equivalent:

    ```javascript filename="docusaurus.config.js"
    headTags: [
      {
        tagName: "script",
        attributes: {
          src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
          defer: "true",
        },
      },
    ],
    ```

    Rebuild with `npm run build` and deploy. The tag is not hot-reloaded into a running `npm run start` session until you restart it.

    <Callout type="info">
      Docusaurus builds a single-page app on React Router. Rybbit detects client-side route changes and records them as pageviews, so no extra code is needed for navigation.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Docusaurus pages are React, so you can fire events from a component and use it in MDX:

```jsx filename="src/components/TrackedButton.jsx"
import React from "react";

export default function TrackedButton({ children, eventName, eventData }) {
  const handleClick = () => {
    window.rybbit?.event(eventName, eventData);
  };

  return (
    <button onClick={handleClick} className="button button--primary">
      {children}
    </button>
  );
}
```

```mdx
import TrackedButton from "@site/src/components/TrackedButton";

<TrackedButton eventName="learn_more_clicked" eventData={{ page: "introduction" }}>
  Learn more
</TrackedButton>
```

For site-wide listeners, use a [client module](https://docusaurus.io/docs/advanced/client-modules). `onRouteDidUpdate` runs after every navigation once the DOM is ready:

```javascript filename="src/client-modules/rybbit-events.js"
export function onRouteDidUpdate() {
  document.querySelectorAll('a[target="_blank"]').forEach((link) => {
    link.addEventListener("click", () => {
      window.rybbit?.event("external_link_click", { href: link.href });
    });
  });
}
```

Register it in `docusaurus.config.js` under `clientModules: [require.resolve("./src/client-modules/rybbit-events.js")]`. Client modules also run during server-side rendering, so guard any `window` access.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Drupal (/zh/docs/guides/drupal)





The [Rybbit module](https://www.drupal.org/project/rybbit) on Drupal.org adds the tracking script to every page and can pass logged-in user details to Rybbit, so you enter a Site ID instead of editing your theme. It requires Drupal 10.3 or later.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Drupal [#add-the-snippet-to-drupal]

    <Tabs items="[&#x22;Rybbit module&#x22;, &#x22;Theme template&#x22;]">
      <Tab>
        1. Install and enable the module:

           ```bash
           composer require drupal/rybbit
           drush en rybbit
           ```

        2. Go to **Configuration → Web services → Rybbit analytics** (`/admin/config/services/rybbit`). Your account needs the *administer rybbit* permission.

        3. Enter your **Site ID** and save.

        Optional settings on the same page:

        * **Script URL**: defaults to Rybbit cloud. Point it at your own instance if you self-host Rybbit.
        * **Visibility**: restrict tracking by role or by page path, each in include or exclude mode.
        * **Identify logged-in users**: calls `identify()` with the user's UUID by default, and sends traits you define as key/value pairs. `username`, `name` and `email` are recognised trait names.
        * The module also exposes hooks for altering the sitewide and per-user tracking data from your own module.
      </Tab>

      <Tab>
        If you cannot install contributed modules, copy `core/modules/system/templates/html.html.twig` into your theme's `templates` folder and add the snippet just before `</head>`:

        ```twig
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Clear caches afterwards so Drupal picks up the new template.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Script missing after saving settings**: pages are served from Drupal's page cache. Clear caches with `drush cr` or **Configuration → Development → Performance → Clear all caches**.
* **Visitors are tracked but you are not**: check the role and path visibility settings on the module page. Excluding the administrator role is a common setup.
* **Logged-in users appear anonymous**: enable **Identify logged-in users** in the module settings; without it Drupal accounts are tracked like any other visitor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Duda (/zh/docs/guides/duda)





Duda has a site-wide **Header HTML** panel in the site settings with two fields: **Head HTML**, printed inside `<head>` on every page, and **Body End HTML**, printed before `</body>`. The snippet goes into Head HTML, and the site must be republished for it to reach the live site.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Duda [#add-the-snippet-to-duda]

    1. In the editor's side panel, click **More**, then **Settings**.
    2. Click **Header HTML**.
    3. Paste the snippet into **Head HTML** and click **Save**.
    4. **Republish** the site. Saved header code shows in the editor and preview, but the live site is only updated on republish.

    Head HTML accepts `<script>`, `<link>` and `<meta>` tags; anything else is stripped on save. The tracking snippet is a single `<script>` tag, so it is kept.

    To limit tracking to one page instead, open that page's **settings** (gear icon), click **SEO** and paste the snippet into that page's **Header HTML**.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the live page source**: the site was not republished. Republish after every change to Header HTML.
* **Code disappears after saving**: Head HTML strips tags other than `<script>`, `<link>` and `<meta>`. Paste only the script tag, without wrapping HTML or comments.
* **Consent management app in use**: Duda loads Head HTML before consent banners can intercept it. If you need the tracker gated by consent, put the snippet in **Body End HTML** instead, where the consent app can control it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ecwid (/zh/docs/guides/ecwid)





An Ecwid by Lightspeed store runs either on Ecwid's hosted **Instant Site** or embedded in a page on another platform. On Instant Site the snippet goes into the site's header code setting; for an embedded store it goes into the `<head>` of the host site, and the storefront Ecwid renders inside that page is tracked with it.

<Callout type="warn">
  Custom code on Instant Site is available on the **Venture**, **Business** and **Unlimited** plans. The free Starter plan has no custom code fields.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ecwid [#add-the-snippet-to-ecwid]

    <Tabs items="[&#x22;Instant Site&#x22;, &#x22;Embedded store&#x22;]">
      <Tab>
        1. From your Ecwid admin, go to **Website** (or **Overview → Manage Instant Site**).
        2. Scroll down to **SEO settings** and click **Add Code** under **Header meta tags and site verification**.
        3. Paste the snippet and save.
        4. Reload your Instant Site in the browser; there is no separate publish step for this setting.

        The **Custom JavaScript code** field under **Advanced website settings** on the same page also works, but it prints code at the end of `<body>`, so prefer the header field.
      </Tab>

      <Tab>
        The store is rendered by Ecwid's embed script inside your own page, so add the snippet to the `<head>` of the host site with that platform's method. See the [integration guides](/docs/guides) for WordPress, Wix, Squarespace, Webflow and others.

        One snippet covers the whole store: product pages, cart and checkout all render inside the same host page.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Ecwid's storefront JavaScript API fires `Ecwid.OnOrderPlaced` with the order right after a customer places it. Add this where the `Ecwid` object already exists: on Instant Site, under **Advanced website settings → Custom JavaScript code**; on an embedded store, after the Ecwid embed script on the host page.

```html
<script>
Ecwid.OnAPILoaded.add(function () {
  Ecwid.OnOrderPlaced.add(function (order) {
    window.rybbit.event('purchase', {
      transaction_id: order.vendorNumber,
      value: order.total,
      tax: order.tax,
      shipping: order.shipping,
      items: order.items.map(function (item) {
        return { item_id: item.sku, item_name: item.name, price: item.price, quantity: item.quantity };
      })
    });
  });
});
</script>
```

`vendorNumber` is the order number customers see in emails; `orderNumber` is Ecwid's internal ID. Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.

Ecwid also has a **Custom tracking code on Order Confirmation page** field under **Settings → General → Tracking & Analytics** (same plans as above). Code there runs on the `/checkout/order-confirmation` page and can use Ecwid's template variables when wrapped in `<#noescape>`:

```html
<script>
<#noescape>
document.addEventListener('DOMContentLoaded', function () {
  window.rybbit.event('purchase', { transaction_id: "${order.number}", value: ${order.total} });
});
</#noescape>
</script>
```

Use one method or the other, not both, or every order is counted twice.

## Troubleshooting [#troubleshooting]

* **No Add Code button under SEO settings**: the store is on the Starter plan. Custom code needs Venture or higher.
* **`Ecwid is not defined`**: the purchase snippet ran before Ecwid's script. Move it below the embed script, or keep it in the Instant Site **Custom JavaScript code** field, which runs at the end of the page.
* **Embedded store, no pageviews**: the snippet belongs to the host site, not to Ecwid. Check the host page's source for `script.js?siteId=`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Electron (/zh/docs/guides/electron)





An Electron renderer is a Chromium page, so Rybbit runs in it the same way it runs in a browser. For a renderer built with a bundler (Vite, webpack, the Electron Forge templates) install the `@rybbit/js` SDK and initialise it in the renderer entry file; for a plain HTML renderer put the snippet in the `<head>` of the HTML file the window loads. In both cases allow `https://app.rybbit.io` in the renderer's Content Security Policy.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Electron [#add-the-snippet-to-electron]

    <Tabs items="[&#x22;@rybbit/js SDK&#x22;, &#x22;Script tag&#x22;]">
      <Tab>
        The SDK is bundled with your renderer code, so nothing is loaded from a CDN at runtime and `script-src 'self'` stays intact.

        1. Install the package in your project:

        ```bash
        npm install @rybbit/js
        ```

        2. Initialise it once in the renderer entry file, before any other tracking call:

        ```js title="src/renderer.js"
        import rybbit from "@rybbit/js";

        await rybbit.init({
          analyticsHost: "https://app.rybbit.io/api",
          siteId: "YOUR_SITE_ID",
        });
        ```

        3. Allow the analytics host in `connect-src`. Electron recommends a CSP for every renderer; when the renderer is loaded from a file, HTTP headers are not available, so use the meta tag:

        ```html title="src/index.html"
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'self'; connect-src 'self' https://app.rybbit.io"
        />
        ```
      </Tab>

      <Tab>
        Paste the snippet into the `<head>` of the renderer HTML and allow the host in both `script-src` (the script itself) and `connect-src` (its requests):

        ```html title="src/index.html"
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'self'; script-src 'self' https://app.rybbit.io; connect-src 'self' https://app.rybbit.io"
        />
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        If you set the CSP from the main process with `session.defaultSession.webRequest.onHeadersReceived` instead, add the same two sources there.
      </Tab>
    </Tabs>

    Both methods track in-app navigation without extra code: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so history-mode and hash-mode routers are covered.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Requests are blocked on the `file://` origin**: Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only. A renderer opened with `win.loadFile()` runs on the `file://` origin and sends `Origin: null`, so Chromium blocks the `POST` to `/api/track` before it leaves the app. The same applies to custom schemes registered with `protocol.handle()`. Load the renderer over http(s) with `win.loadURL()` (your dev server in development, a hosted or locally served build in production) and tracking works.
* **Console shows a CSP violation**: the message names the directive that blocked the request. Add `https://app.rybbit.io` to that directive; `connect-src` covers the SDK, and the script tag also needs `script-src`.
* **Hostname is empty in the dashboard**: pageviews report the renderer's `window.location.hostname`, which is empty for `file://` pages. Filter by site rather than hostname.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Eleventy (/zh/docs/guides/eleventy)





Eleventy renders every page through a layout in `_includes/`, so the snippet goes in your base layout's `<head>`. Keep the site ID in a global data file under `_data/` so the layout stays free of hard-coded values.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Eleventy [#add-the-snippet-to-eleventy]

    1. Create `_data/rybbit.json` (create the `_data/` directory if it does not exist). Every template can then read it as `rybbit`. Change `instanceUrl` only if you self-host:

       ```json title="_data/rybbit.json"
       {
         "siteId": "YOUR_SITE_ID",
         "instanceUrl": "https://app.rybbit.io"
       }
       ```

    2. Open your base layout and add the tag inside `<head>`. The `eleventy.env.runMode` check keeps the script out of `--serve` and `--watch` runs, so local development is not tracked; the `rybbit.siteId` check keeps it out of builds with no ID configured.

    <Tabs items="[&#x22;Nunjucks&#x22;, &#x22;Liquid&#x22;]">
      <Tab value="Nunjucks">
        ```html title="_includes/base.njk"
        <head>
          ...
          {% if eleventy.env.runMode == "build" and rybbit.siteId %}
            <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>

      <Tab value="Liquid">
        ```html title="_includes/base.liquid"
        <head>
          ...
          {% if eleventy.env.runMode == "build" and rybbit.siteId %}
            <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>
    </Tabs>

    3. Build and deploy the generated `_site/` directory:

       ```bash
       npx @11ty/eleventy
       ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `npx @11ty/eleventy --serve` sets `runMode` to `serve`, so the guard removes the tag. Check the output of a plain build instead.
* **Eleventy 1.x**: `eleventy.env.runMode` was added in Eleventy 2.0. On older versions drop the `runMode` condition and keep only the `rybbit.siteId` check.
* **Custom data directory**: if your config sets `dir.data`, put `rybbit.json` in that directory instead of `_data/`.
* **Several layouts**: a page only gets the tag if its layout chain ends in the layout you edited. Pages with `layout: none` or a different base layout need the tag added there too.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ember (/zh/docs/guides/ember)





An Ember app has one HTML shell that every route renders into. Apps created with the current Vite-based `ember new` blueprint keep it at `index.html` in the project root; classic ember-cli apps keep it at `app/index.html`. Paste the snippet into the `<head>` of that file.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ember [#add-the-snippet-to-ember]

    Open `index.html` (or `app/index.html` in a classic ember-cli app) and paste the snippet inside `<head>`, after the `{{content-for "head"}}` placeholder:

    ```handlebars title="index.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8">
        <title>MyApp</title>
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        {{content-for "head"}}

        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>

        <link integrity="" rel="stylesheet" href="/@embroider/virtual/vendor.css">
        <link integrity="" rel="stylesheet" href="/@embroider/virtual/app.css">

        {{content-for "head-footer"}}
      </head>
      <body>
        {{content-for "body"}}
        ...
        {{content-for "body-footer"}}
      </body>
    </html>
    ```

    Keep the `{{content-for}}` placeholders in place; the build fills them in. Route transitions made by Ember's router (the default `history` location type) are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a component action. Guard the call so a blocked or still-loading script does not throw.

```js title="app/components/signup-button.gjs"
import Component from "@glimmer/component";
import { on } from "@ember/modifier";

export default class SignupButton extends Component {
  trackSignup = () => {
    if (window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  <template>
    <button type="button" {{on "click" this.trackSignup}}>Sign up</button>
  </template>
}
```

## Troubleshooting [#troubleshooting]

* **`index.html` is also used by the test runner**: `tests/index.html` is a separate file. Do not add the snippet there, or test runs send pageviews to your dashboard.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# FastAPI (/zh/docs/guides/fastapi)





FastAPI serves HTML through `Jinja2Templates`, so the snippet goes into the `<head>` of the base template your pages extend. Keep the site ID in a `pydantic-settings` class and register it as a Jinja global so every template can render the tag without passing it through each route.

<Callout type="info">
  The tracking script runs in a browser, so it only applies to routes that return template-rendered HTML. JSON endpoints have nothing for it to track.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to FastAPI [#add-the-snippet-to-fastapi]

    #### Configure the site ID [#configure-the-site-id]

    Install `pydantic-settings` and `jinja2` if you have not already:

    ```bash
    pip install pydantic-settings jinja2
    ```

    Define the settings, reading from the environment and an optional `.env` file:

    ```python filename="config.py"
    from pydantic_settings import BaseSettings, SettingsConfigDict


    class Settings(BaseSettings):
        model_config = SettingsConfigDict(env_file=".env")

        rybbit_instance_url: str = "https://app.rybbit.io"
        rybbit_site_id: str = ""


    settings = Settings()
    ```

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    #### Register the values with Jinja [#register-the-values-with-jinja]

    `Jinja2Templates` exposes its environment as `templates.env`, so add the settings as globals once, next to where you create the templates object:

    ```python filename="main.py"
    from fastapi import FastAPI, Request
    from fastapi.responses import HTMLResponse
    from fastapi.templating import Jinja2Templates

    from config import settings

    app = FastAPI()
    templates = Jinja2Templates(directory="templates")
    templates.env.globals["rybbit_instance_url"] = settings.rybbit_instance_url
    templates.env.globals["rybbit_site_id"] = settings.rybbit_site_id


    @app.get("/", response_class=HTMLResponse)
    async def index(request: Request):
        return templates.TemplateResponse(request=request, name="index.html")
    ```

    #### Add the tag to your base template [#add-the-tag-to-your-base-template]

    Open the template your pages extend, usually `templates/base.html`, and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My App{% endblock %}</title>

        {% if rybbit_site_id %}
        <script src="{{ rybbit_instance_url }}/api/script.js?siteId={{ rybbit_site_id }}" defer></script>
        {% endif %}
    </head>
    ```

    The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable. Templates that do not extend the base need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `Settings()` reads the environment when the module is imported, so restart Uvicorn (or your process manager) after changing `RYBBIT_SITE_ID`.
* **Several `Jinja2Templates` instances**: globals are per environment. If routers create their own `Jinja2Templates`, set the globals on each, or share one instance from a module.
* **Content Security Policy**: if middleware sets one, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Flask (/zh/docs/guides/flask)





Flask renders Jinja templates, and most apps extend a shared base layout, so the snippet goes into that layout's `<head>`. Flask exposes `app.config` to every template as `config`, so store the site ID there and reference it from the template.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Flask [#add-the-snippet-to-flask]

    #### Configure the site ID [#configure-the-site-id]

    Flask loads any environment variable prefixed with `FLASK_` into `app.config` when you call `from_prefixed_env()`. Set the values in your environment (`flask run` also reads a `.env` file when python-dotenv is installed):

    ```bash filename=".env"
    FLASK_RYBBIT_INSTANCE_URL=https://app.rybbit.io
    FLASK_RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then load them where you create the app:

    ```python filename="app.py"
    from flask import Flask, render_template

    app = Flask(__name__)
    app.config.setdefault("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
    app.config.from_prefixed_env()


    @app.route("/")
    def index():
        return render_template("index.html")
    ```

    `from_prefixed_env()` parses values as JSON where it can, so a numeric site ID arrives as an `int`. It renders the same in the template.

    If you keep configuration in a Python file or class instead, add `RYBBIT_INSTANCE_URL` and `RYBBIT_SITE_ID` there and load it with `app.config.from_object()`.

    #### Add the tag to your base layout [#add-the-tag-to-your-base-layout]

    Open the template that your pages extend, usually `templates/base.html` (or `templates/layout.html`), and add the tag inside `<head>`:

    ```jinja filename="templates/base.html"
    <head>
        <meta charset="utf-8">
        <title>{% block title %}My App{% endblock %}</title>

        {% if config.RYBBIT_SITE_ID %}
        <script src="{{ config.RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ config.RYBBIT_SITE_ID }}" defer></script>
        {% endif %}
    </head>
    ```

    `config` is part of Flask's standard template context, so no context processor is needed. The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is unset, so local development is not tracked unless you set the variable.

    Templates that do not extend the base layout need the same tag in their own `<head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `from_prefixed_env()` reads the environment when the app is created, so restart the server after changing `FLASK_RYBBIT_SITE_ID`. Check `app.config["RYBBIT_SITE_ID"]` in `flask shell`.
* **Macros imported into other templates**: `config` is added to the render context, not to imported templates. A macro that outputs the tag must be imported `with context`.
* **Content Security Policy**: if you set one with Flask-Talisman or similar, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `FLASK_RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Flutter web (/zh/docs/guides/flutter-web)





A Flutter web app is served from the `web/index.html` template in your project, which `flutter build web` copies to `build/web/index.html`. The snippet goes in that file's `<head>`. Flutter draws the UI into a canvas rather than DOM elements, so pageviews and manual events work as usual while anything that inspects the DOM does not.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Flutter web [#add-the-snippet-to-flutter-web]

    1. Open `web/index.html` in your Flutter project.
    2. Paste the snippet inside `<head>`, above the `flutter_bootstrap.js` script that Flutter generates:

    ```html title="web/index.html"
    <head>
      <meta charset="UTF-8" />
      <title>My App</title>
      <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    ```

    3. Rebuild with `flutter build web` and deploy the `build/web` folder.

    Navigation is tracked automatically with either URL strategy. Flutter's default hash strategy writes routes as `/#/settings`, and the tracker listens for `hashchange` and records `#/settings` as the path `/settings`. With `usePathUrlStrategy()` the Navigator uses the History API, and the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Flutter widgets are not HTML elements, so `data-rybbit-event` attributes have nothing to attach to. Call `window.rybbit.event()` from Dart through `dart:js_interop` instead:

```dart title="lib/analytics.dart"
import 'dart:js_interop';

@JS('rybbit.event')
external void _rybbitEvent(String name, [JSAny? properties]);

void trackEvent(String name, [Map<String, Object?>? properties]) {
  _rybbitEvent(name, properties?.jsify());
}
```

```dart
ElevatedButton(
  onPressed: () {
    trackEvent('signup_click', {'plan': 'pro'});
  },
  child: const Text('Sign up'),
)
```

Guard the call with `kIsWeb` if the same code also compiles for mobile or desktop targets.

## Troubleshooting [#troubleshooting]

* **Clicks, outbound links and session replay show nothing**: the CanvasKit and Skwasm renderers paint into a single `<canvas>`, so DOM-based features (`data-rybbit-event` attributes, outbound-link tracking, button-click autocapture, session replay) have no elements to observe. Use the Dart interop above for events.
* **Deep links 404 after switching to `usePathUrlStrategy()`**: path URLs need the web server to rewrite every route to `index.html`; the Flutter dev server does this for you, production hosting must be configured.
* **`rybbit` is undefined in Dart**: the snippet is `defer`red, so it is not ready during `main()`. Send events from user interactions, not from app start-up.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Framer (/zh/docs/guides/framer)





Framer has a **Custom Code** section in the site settings that injects HTML into the `<head>` of every published page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Framer [#add-the-snippet-to-framer]

    1. Open your Framer project and go to **Site Settings → General**.
    2. Scroll to **Custom Code**.
    3. Paste the snippet into the **Start of `<head>` tag** field (End of `<head>` works too).
    4. Click **Save**, then **Publish**. Custom code only reaches the live site on publish.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Use a **Code Override** to send events from any element in the canvas.

1. Select the element, open **Overrides*&#x2A; in the properties panel, and click **+ File** to create an override file such as `RybbitOverrides.tsx`.
2. Add an override that wraps the element's click handler:

```tsx
// RybbitOverrides.tsx
import type { ComponentType } from "react";

export function withRybbitClick(Component: ComponentType): ComponentType {
  return (props) => {
    const handleClick = () => {
      window.rybbit?.event("cta_click", { label: props.text ?? "cta" });
      props.onClick?.();
    };
    return <Component {...props} onClick={handleClick} />;
  };
}
```

3. Back in the properties panel, pick the file and apply `withRybbitClick` to the element.

The same `window.rybbit.event()` call works inside a **Code Component**.

## Troubleshooting [#troubleshooting]

* **Navigation between pages is not tracked**: Framer sites navigate client-side and the script detects those URL changes. If a view changes without the URL changing, call `window.rybbit.pageview()` from an override when it appears.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Fumadocs (/zh/docs/guides/fumadocs)





Fumadocs is a documentation framework for Next.js, so the snippet goes in the root layout, `app/layout.tsx`, rendered with `next/script` so it is on every page including the docs routes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Fumadocs [#add-the-snippet-to-fumadocs]

    Open `app/layout.tsx` and render the `Script` component inside `<body>`, next to the `RootProvider` that Fumadocs already puts there:

    ```tsx title="app/layout.tsx"
    import { RootProvider } from "fumadocs-ui/provider/next";
    import Script from "next/script";
    import type { ReactNode } from "react";

    export default function Layout({ children }: { children: ReactNode }) {
      return (
        <html lang="en" suppressHydrationWarning>
          <body className="flex flex-col min-h-screen">
            <RootProvider>{children}</RootProvider>
            <Script
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    Use the root layout, not `app/docs/layout.tsx`: the docs layout only wraps pages under `/docs`, so a landing page outside it would be missed.

    Client-side navigation between docs pages is recorded as pageviews automatically. The [Next.js guide](/docs/guides/react/next-js) covers the `Script` component, custom events from client components and proxying through your own domain.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ghost (/zh/docs/guides/ghost)





Ghost has a built-in **Code injection** setting that adds HTML to the `<head>` of every page, so no theme edits are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ghost [#add-the-snippet-to-ghost]

    1. Open **Ghost Admin** and click the **Settings** gear in the bottom left.
    2. Under **Advanced**, open **Code injection**.
    3. Paste the snippet into **Site header** and click **Save**.

    If you maintain your own theme instead, add the snippet to `default.hbs` just before `</head>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Ghost(Pro) with a custom theme**: code injection still applies on top of the theme, so prefer it over editing `default.hbs`.
* **Member-only content**: pages behind the paywall are tracked like any other page for visitors who can view them.
* **Portal and newsletter previews** render in an iframe and are not tracked.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# GitBook (/zh/docs/guides/gitbook)





GitBook does not let you add custom scripts to a published site, and its integration platform does not let third parties inject them either. This page explains what that means and what your options are.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to GitBook [#add-the-snippet-to-gitbook]

    <Callout type="warn">
      There is currently no supported way to load the Rybbit snippet on a GitBook-hosted site. The old **Custom scripts → Head** setting was removed, and GitBook's [integration scopes](https://gitbook.com/docs/developers/integrations/configurations) reserve `site:script:inject` for GitBook's own integrations: "Building integrations that inject JavaScript into a site or space is not possible at this time."
    </Callout>

    Your options:

    * **Use GitBook's built-in analytics.** The **Insights** section in the GitBook app reports page views and search terms for published sites without any script.
    * **Wait for a native integration.** A Rybbit integration would need GitBook to build or approve it. Ask GitBook support for it, and watch the [Rybbit roadmap](/docs/roadmap).
    * **Host the docs elsewhere.** [Docusaurus](/docs/guides/docusaurus), [Mintlify](/docs/guides/mintlify), [VitePress](/docs/guides/vitepress), [Starlight](/docs/guides/starlight) and [Fumadocs](/docs/guides/fumadocs) all take the snippet directly, and GitBook can export a space as Markdown to migrate.

    The rest of your site (marketing pages, app, blog) is unaffected: add the snippet there as usual so traffic from the docs is still attributed by referrer.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Google Tag Manager (/zh/docs/guides/google-tag-manager)





Google Tag Manager loads Rybbit through a **Custom HTML** tag fired on **All Pages**, so nothing in your site's code changes. Events you already push to the `dataLayer` can be forwarded to Rybbit with a second tag.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Google Tag Manager [#add-the-snippet-to-google-tag-manager]

    1. Open your GTM container and go to **Tags → New**.
    2. Under **Tag Configuration**, choose **Custom HTML** and paste the snippet:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    3. Under **Triggering**, choose **All Pages** (the built-in Page View trigger).
    4. Name the tag, for example `Rybbit - Loader`, and click **Save**.
    5. Click **Submit** and publish the container version.

    <Callout type="warn">
      GTM rebuilds Custom HTML tags before injecting them and can drop non-standard attributes. Keep the site ID in the URL (`?siteId=`) as shown; the older `data-*` attribute form is not reliable here.
    </Callout>

    Use **Preview** mode to confirm the tag fires on page load before publishing.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Once the loader tag is published, `window.rybbit` is available to your own JavaScript and to other GTM tags.

#### Forward dataLayer events [#forward-datalayer-events]

If your site already pushes events like `dataLayer.push({ event: "signup" })`, one tag can forward them to Rybbit:

1. Create a **Custom Event** trigger. Set the event name to a regex such as `signup|purchase|add_to_cart` (tick **Use regex matching**).
2. Create a **Custom HTML** tag with that trigger:

```html
<script>
  if (window.rybbit) {
    window.rybbit.event("{{Event}}", {
      page: "{{Page Path}}",
      referrer: "{{Referrer}}"
    });
  }
</script>
```

`{{Event}}`, `{{Page Path}}` and `{{Referrer}}` are GTM built-in variables. Add a **Data Layer Variable** for any custom field you push (for example `plan`) and reference it the same way.

#### Use GTM's click and form triggers [#use-gtms-click-and-form-triggers]

The same pattern works with built-in **Click** and **Form Submission** triggers:

```html
<script>
  if (window.rybbit) {
    window.rybbit.event("cta_clicked", {
      text: "{{Click Text}}",
      url: "{{Click URL}}"
    });
  }
</script>
```

Enable the **Click Text** and **Click URL** built-in variables under **Variables → Configure**.

## Troubleshooting [#troubleshooting]

* **Event tag fires before Rybbit loads**: the loader script is deferred, so an event tag on the same page load may run first and hit the `if (window.rybbit)` guard. Open the event tag's **Advanced Settings → Tag Sequencing** and set the loader tag to fire before it, or trigger the event tag on **Window Loaded** instead of **Page View**.
* **Consent mode**: if your container gates tags on consent, add the loader tag to the same consent group as your other analytics tags, otherwise it never fires.
* **Tag shows in Preview but not live**: the container version was not published. Click **Submit** and publish.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hexo (/zh/docs/guides/hexo)





Hexo 5 and later ship an injector API that adds HTML to the `<head>` of every generated page from a small file in your site's `scripts/` directory, so no theme edits are needed. Editing the theme's head partial is the fallback for older versions.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hexo [#add-the-snippet-to-hexo]

    <Tabs items="[&#x22;Injector script&#x22;, &#x22;Theme layout&#x22;]">
      <Tab value="Injector script">
        1. Add your site ID to the site `_config.yml` at the root of your project (not the theme config). `instance_url` is only needed if you self-host:

           ```yaml title="_config.yml"
           rybbit:
             site_id: "YOUR_SITE_ID"
             instance_url: "https://app.rybbit.io"
           ```

        2. Create `scripts/rybbit.js` (create the `scripts/` directory if it does not exist). Hexo loads every file in this directory at startup with the `hexo` object in scope:

           ```javascript title="scripts/rybbit.js"
           const { site_id: siteId, instance_url: instanceUrl = "https://app.rybbit.io" } =
             hexo.config.rybbit || {};

           if (siteId) {
             hexo.extend.injector.register(
               "head_end",
               `<script src="${instanceUrl}/api/script.js?siteId=${siteId}" defer></script>`
             );
           }
           ```

           `head_end` places the tag right before `</head>`. With no third argument the injector applies to every page type.
      </Tab>

      <Tab value="Theme layout">
        Open your theme's head partial and paste the snippet before `</head>`. For the default Landscape theme that file is `themes/landscape/layout/_partial/head.ejs`; other themes keep an equivalent partial under `layout/`.

        ```html title="themes/landscape/layout/_partial/head.ejs"
          ...
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Theme updates overwrite this file, so prefer the injector when your Hexo version supports it.
      </Tab>
    </Tabs>

    Regenerate and deploy the `public/` directory:

    ```bash
    hexo clean && hexo generate
    ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **`hexo.extend.injector` is undefined**: the injector API arrived in Hexo 5.0. Check `hexo version` and upgrade, or use the theme layout method.
* **Tag missing after adding the script**: run `hexo clean` before `hexo generate`; Hexo caches rendered output in `db.json` and can serve stale pages.
* **Local previews are tracked**: `hexo server` runs the same injector as `hexo generate`. Leave `site_id` empty in a local copy of `_config.yml`, or accept the local pageviews.
* **Theme config vs site config**: `hexo.config` reads the root `_config.yml`, not `themes/<name>/_config.yml`. Put the `rybbit` block in the root file.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hostinger Website Builder (/zh/docs/guides/hostinger)





Hostinger Website Builder has a **Custom code** integration in the website settings that adds code to every page. Script tags are placed at the end of `<body>` by default; a `data-render-head` attribute moves them into `<head>`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hostinger Website Builder [#add-the-snippet-to-hostinger-website-builder]

    1. Open your site in the builder and click &#x2A;*⋯** (More) at the top to open the website settings, then choose **Integrations**.
    2. Select **Custom code**.
    3. Paste the snippet with `data-render-head` added so it loads from `<head>`:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer data-render-head></script>
    ```

    4. Save the changes, then click **Update website** to publish. Custom code runs on the live site and in preview, not inside the editor.

    Without `data-render-head` the builder moves `<script>` tags to the end of `<body>`. The tracker still works there; the attribute only makes it load earlier.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **No requests to `script.js` in the editor**: expected. Integrations are injected into the published site only, so check the live URL or the preview.
* **Snippet saved but not in the page source**: the site was not updated after saving. Click **Update website**.
* **Site breaks after adding several snippets**: paste snippets one after another, never nested inside each other. If the page still fails, remove all custom code, update, and add the snippets back one at a time.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# htmx (/zh/docs/guides/htmx)





htmx pages are plain server-rendered HTML, so the snippet goes in the `<head>` of your base layout next to the htmx script tag, in whichever template your server uses for the full-page response.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to htmx [#add-the-snippet-to-htmx]

    Open the template that renders the full HTML document (the one that already loads htmx) and paste the snippet inside `<head>`:

    ```html title="layout.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My htmx App</title>
        <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.10/dist/htmx.min.js"></script>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <main id="content" hx-boost="true">...</main>
      </body>
    </html>
    ```

    Only full-page responses need the tag. Partial responses that htmx swaps into the page must not include it, or the script is re-evaluated on every swap.

    Navigations that htmx records in browser history are tracked automatically as pageviews: `hx-push-url` and `hx-boost` call `history.pushState()`, `hx-replace-url` calls `history.replaceState()`, and the back and forward buttons fire `popstate`. All three are hooked by the tracker. A swap without `hx-push-url` leaves the URL unchanged and is not counted as a pageview; send a [custom event](/docs/track-events) for those interactions instead.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Use the `data-rybbit-event` attribute on the element that triggers the request. The tracker listens for clicks on `document`, so it also works on content that htmx swapped in after the page loaded:

```html
<button
  hx-post="/subscribe"
  hx-target="#form"
  data-rybbit-event="newsletter_subscribe"
  data-rybbit-prop-plan="free"
>
  Subscribe
</button>
```

To record an event when the server has actually processed the request, listen for htmx's `htmx:afterRequest` event and call `window.rybbit.event()` from there.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# HubSpot (/zh/docs/guides/hubspot)





HubSpot Content Hub (formerly CMS Hub) has a **Site header HTML** setting that injects code into the `<head>` of every website page, landing page, blog post and knowledge base article on a domain, so no template edits are needed. Individual pages can add or override code from the content editor.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to HubSpot [#add-the-snippet-to-hubspot]

    <Tabs items="[&#x22;Site header HTML&#x22;, &#x22;Single page&#x22;]">
      <Tab>
        This adds the snippet to all HubSpot-hosted content on a domain.

        1. In your HubSpot account, click the **settings** icon in the top navigation bar.
        2. In the left sidebar, go to **Content > Pages**.
        3. Use the **Choose a domain to edit its settings** dropdown to pick the domain, or stay on the default settings to apply the code to every domain.
        4. Paste the snippet into the **Site header HTML** field.
        5. Click **Save**.

        If a domain has **Override default settings** turned on, the default header code no longer applies to it. Add the snippet to that domain's own settings as well.
      </Tab>

      <Tab>
        Use this to track a single page, or when someone else controls the domain settings.

        1. Open **Content > Website Pages** (or **Landing Pages**, **Blog**, **Knowledge Base**) and click the page name to open the editor.
        2. Click the **Settings** menu, then select **Advanced**.
        3. Under **Additional code snippets**, paste the snippet into the **Head HTML** field.
        4. Click **Update** or **Publish**.

        Per-page head HTML is added on top of the site header HTML, so a page tracked by both methods loads the script twice. Pick one.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

HubSpot forms submit inside the page without a full reload, so track them with a custom event. Add `data-rybbit-event` to a call-to-action button, or listen for HubSpot's form-submitted message in a small script placed after the snippet:

```html
<script>
  window.addEventListener("message", function (event) {
    if (event.data.type === "hsFormCallback" && event.data.eventName === "onFormSubmitted") {
      window.rybbit.event("form_submitted", { formId: event.data.id });
    }
  });
</script>
```

See [Track custom events](/docs/track-events) for the event API.

## Troubleshooting [#troubleshooting]

* **Snippet missing on one domain**: the site header HTML is per domain. Check whether that domain has **Override default settings** enabled and add the snippet there.
* **Duplicate pageviews**: the same page has the snippet in both site header HTML and its own **Head HTML**. Remove one.
* **Editor and preview**: the content editor renders pages in an iframe with unpublished changes. Previews are tracked like any other visit if they load the script, so avoid checking analytics from the editor.
* **Quotes**: header HTML set at the domain level also loads on HubSpot quotes hosted on that domain.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Hugo (/zh/docs/guides/hugo)





Hugo builds every page from templates under `layouts/`, so the cleanest place for the snippet is a partial template that your base template includes on every page.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Hugo [#add-the-snippet-to-hugo]

    1. Add your site ID under `params` in your Hugo config (`hugo.toml`, or `config.toml` in older Hugo versions). `rybbitInstanceURL` is only needed if you self-host:

       ```toml title="hugo.toml"
       [params]
         rybbitSiteID = "YOUR_SITE_ID"
         rybbitInstanceURL = "https://app.rybbit.io"
       ```

    2. Create `layouts/partials/rybbit-analytics.html` (create the `layouts/partials/` directory if it does not exist):

       ```html title="layouts/partials/rybbit-analytics.html"
       {{ if and (not hugo.IsServer) .Site.Params.rybbitSiteID }}
         <script src="{{ .Site.Params.rybbitInstanceURL | default "https://app.rybbit.io" }}/api/script.js?siteId={{ .Site.Params.rybbitSiteID }}" defer></script>
       {{ end }}
       ```

       `not hugo.IsServer` skips the script during `hugo server`, so local development is not tracked. The `rybbitSiteID` check keeps the tag out of builds that have no ID configured.

    3. Include the partial from your base template, typically `layouts/_default/baseof.html`, inside `<head>`. If your theme owns `baseof.html`, copy it into your project's `layouts/_default/` first so the theme can be updated without losing the change; a theme footer partial such as `layouts/partials/footer.html` also works.

       ```html title="layouts/_default/baseof.html"
       <head>
         ...
         {{ partial "rybbit-analytics.html" . }}
       </head>
       ```

    4. Build with `hugo` and deploy the generated `public/` directory.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `hugo server` never emits it because of the `hugo.IsServer` guard. Check the output of a production `hugo` build instead.
* **Theme overrides**: a file at `layouts/_default/baseof.html` in your project takes precedence over the theme's copy, so make sure you edited the one Hugo actually renders.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Integration guides (/zh/docs/guides)



Rybbit works on any site that can load a script tag. Each guide below shows exactly where the tracking snippet goes on that platform and how to confirm it is working.

Don't see your platform? Paste the snippet from **Site Settings → Tracking Script** into the `<head>` of every page, or follow the [tracking script](/docs/script) reference.

<GuideIndex />


# Instapage (/zh/docs/guides/instapage)





Instapage takes custom scripts at two levels: **Workspace scripts** (under **Assets > Scripts**) apply to every page in a workspace, and each page also has its own **JavaScript** and **HTML/CSS** settings with a **Head** section. Custom HTML, CSS and JavaScript are included on all Instapage plans; Workspace scripts are limited to some subscriptions and show an upgrade prompt otherwise.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Instapage [#add-the-snippet-to-instapage]

    <Tabs items="[&#x22;Workspace scripts&#x22;, &#x22;Single page&#x22;]">
      <Tab>
        1. In the left menu, open **Assets**, then **Scripts**.
        2. Paste the snippet into the **Head** section.
        3. Above the editor, choose how it applies: option **A** adds it to every past and future page in the workspace; **B** leaves it off until you switch it on per page under **Scripts & Privacy**; **B + C** turns it on for all pages but lets you disable it per page.
        4. Click **Apply**.

        Workspace scripts load on the live URL before any page-level script, so the snippet is in place before other code on the page runs.
      </Tab>

      <Tab>
        1. Open the page in the builder and click **Settings** in the right sidebar.
        2. Open the **HTML/CSS** tab and paste the snippet into **Head**. (The **JavaScript** tab has the same three sections and wraps your code in `<script>` tags automatically; the snippet already has its own tag, so HTML/CSS is the simpler choice.)
        3. **Publish** the page. Custom code runs only on the live, published page, not in the editor or preview.
      </Tab>
    </Tabs>

    <Callout type="info">
      If you use Instapage's privacy compliance banner, put the snippet in the page's **Scripts & Privacy** section instead so it fires only after the visitor accepts.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: the page was saved but not republished. Custom code only reaches the live URL on publish.
* **Assets > Scripts shows an upgrade prompt**: Workspace scripts are not on your subscription. Add the snippet per page instead.
* **Duplicate pageviews**: the snippet is both a workspace script and a page-level script. Keep one copy.
* **Old version still served**: clear your browser cache after publishing; Instapage notes cached copies can outlive an update.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Jekyll (/zh/docs/guides/jekyll)





Jekyll renders every page through a layout, usually `_layouts/default.html`. Put the snippet in an include file that the layout pulls in, or paste it into the layout directly.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Jekyll [#add-the-snippet-to-jekyll]

    <Tabs items="[&#x22;Include file&#x22;, &#x22;Layout file&#x22;]">
      <Tab value="Include file">
        1. Add your site ID to `_config.yml`. `rybbit_instance_url` is only needed if you self-host:

           ```yaml title="_config.yml"
           rybbit_site_id: "YOUR_SITE_ID"
           rybbit_instance_url: "https://app.rybbit.io"
           ```

        2. Create `_includes/rybbit-analytics.html` (create the `_includes/` directory if it does not exist):

           ```html title="_includes/rybbit-analytics.html"
           {% if jekyll.environment == "production" and site.rybbit_site_id %}
             <script src="{{ site.rybbit_instance_url | default: 'https://app.rybbit.io' }}/api/script.js?siteId={{ site.rybbit_site_id }}" defer></script>
           {% endif %}
           ```

           The `jekyll.environment` check keeps the script out of local `jekyll serve` builds; the `site.rybbit_site_id` check keeps it out of builds with no ID configured.

        3. Include it from your layout's `<head>`:

           ```html title="_layouts/default.html"
           <head>
             ...
             {% include rybbit-analytics.html %}
           </head>
           ```
      </Tab>

      <Tab value="Layout file">
        Open `_layouts/default.html` and paste the snippet inside `<head>`, wrapped in a production check so local `jekyll serve` builds are not tracked:

        ```html title="_layouts/default.html"
        <head>
          ...
          {% if jekyll.environment == "production" %}
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          {% endif %}
        </head>
        ```
      </Tab>
    </Tabs>

    Build for production and deploy the generated `_site/` directory:

    ```bash
    JEKYLL_ENV=production jekyll build
    ```

    GitHub Pages sets `jekyll.environment` to `production` during its own build, so no extra configuration is needed there.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `jekyll serve` and a plain `jekyll build` run with `jekyll.environment` set to `development`, so the production guard removes the tag. Build with `JEKYLL_ENV=production` and check that output.
* **Config changes not applied**: Jekyll reads `_config.yml` once at startup, so restart `jekyll serve` after adding `rybbit_site_id`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Joomla (/zh/docs/guides/joomla)





Joomla has no built-in head-code setting, so the snippet goes in either a **Custom** module assigned to every page or in your template's `index.php`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Joomla [#add-the-snippet-to-joomla]

    <Tabs items="[&#x22;Custom module&#x22;, &#x22;Template file&#x22;]">
      <Tab>
        No file edits are needed, and the module survives template updates.

        1. In the Administrator panel go to **Content → Site Modules** (**Extensions → Modules** on Joomla 3), click **New** and choose **Custom**.

        2. Set **Title** to `Rybbit`, **Show Title** to **Hide**, and **Position** to any position your template renders on every page. Templates rarely expose a `<head>` position; the loader below moves the script into the head from wherever the module is rendered.

        3. In the editor, use the **Toggle Editor** button (or **Code** view) so the script is not stripped, then paste:

           ```html
           <script>
           (function () {
             var s = document.createElement("script");
             s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
             s.defer = true;
             document.head.appendChild(s);
           })();
           </script>
           ```

        4. Set **Status** to **Published**, choose **On all pages** under **Menu Assignment**, and click **Save & Close**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Edit a child template (Joomla 4.1+) or your own copy of the template, otherwise the change is lost on the next template update.
        </Callout>

        1. Go to **System → Site Templates** and open your active template.

        2. Open `index.php` and add the snippet just before `</head>`:

           ```php
           <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
           </head>
           ```

        3. Click **Save & Close**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Module not on the page**: confirm it is published, assigned to **On all pages**, and that the chosen position exists in your template. Then clear the cache under **System → Clear Cache**.
* **TinyMCE strips the script**: open the **Editor - TinyMCE** plugin under **System → Plugins** (**Extensions → Plugins** on Joomla 3) and add `script[src|defer]` to **Extended Valid Elements**, or keep using the toggled-off editor when saving the module.
* **Page caching**: the **System - Page Cache** plugin serves cached HTML, so clear the cache after adding the snippet. The script itself loads client-side and works with cached pages.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Kajabi (/zh/docs/guides/kajabi)





Kajabi has a site-wide **Header Page Scripts** field under **Site details** that puts code in the `<head>` of every page, but it deliberately skips Offer checkout and upsell pages. Those have their own **Checkout Tracking Code** setting, so a full install is two pastes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Kajabi [#add-the-snippet-to-kajabi]

    **Site-wide pages**

    1. From the **Dashboard**, open **Settings**.
    2. Under **Site settings**, click **Site details**.
    3. Scroll to **Page scripts** and paste the snippet into **Header Page Scripts**.
    4. Save.

    **Checkout and upsell pages**

    1. From the **Dashboard**, open **Settings**.
    2. Under **Payment settings**, click **Checkout**.
    3. In the **Checkout Tracking Code** section, click to edit the **Header tracking code** and paste the same snippet.
    4. Save.

    <Callout type="info">
      Do not paste the snippet into a page's **Custom Code** section (under **Customize > Settings**). That field is for CSS and JavaScript without `<style>` or `<script>` tags, and it only applies to that one page.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Checkout pages missing from the dashboard**: Header Page Scripts do not run on Offer checkout or upsell pages. Add the snippet under **Settings > Checkout > Checkout Tracking Code** as well.
* **Both fields filled, one visitor, two sites?** Use the same site ID in both places so a visitor who browses your site and then buys is one session, and funnels can follow them through checkout.
* **Snippet added to a page's Custom Code block instead**: the **Add block > Custom Code** block does accept `<script>` tags, but it only covers that page. Keep the site-wide field as the source of truth.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Kirby (/zh/docs/guides/kirby)





Kirby templates are plain PHP files in `site/templates/`, and shared markup lives in `site/snippets/`. The snippet goes into whichever file owns your `<head>`: the Starterkit's `site/snippets/header.php`, or the template itself in a Plainkit project.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Kirby [#add-the-snippet-to-kirby]

    <Tabs items="[&#x22;Starterkit&#x22;, &#x22;Plainkit&#x22;]">
      <Tab>
        The Starterkit renders the document head from a shared snippet that every template includes with `<?php snippet('header') ?>`.

        1. Open `site/snippets/header.php`.
        2. Add the tag before `</head>`:

        ```php title="site/snippets/header.php"
        <head>
          <meta charset="utf-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title><?= $site->title() ?> | <?= $page->title() ?></title>
          <?= css(['assets/css/index.css', '@auto']) ?>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        3. Save. Every template that calls `snippet('header')` now loads the script.
      </Tab>

      <Tab>
        The Plainkit's `site/templates/default.php` contains only `<h1><?= $page->title() ?></h1>` and no document structure, so add the tag wherever you build your `<head>`. The usual pattern is a header snippet included by each template:

        ```php title="site/snippets/header.php"
        <!DOCTYPE html>
        <html lang="en">
        <head>
          <meta charset="utf-8">
          <title><?= $page->title() ?></title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        <body>
        ```

        ```php title="site/templates/default.php"
        <?php snippet('header') ?>
        <h1><?= $page->title() ?></h1>
        <?php snippet('footer') ?>
        ```
      </Tab>
    </Tabs>

    To keep the site ID out of the snippet, add it to `site/config/config.php` and read it with `<?= option('rybbit.siteId') ?>`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Page cache**: if `cache.pages.active` is enabled in `site/config/config.php`, flush `site/cache/` after editing the snippet or cached pages keep the old head.
* **Multiple header snippets**: templates that include a different header (for example `snippet('header-landing')`) need the tag added there too.
* **Panel is not tracked**: `/panel` is a separate app that does not render your templates, so editing time never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Laravel (/zh/docs/guides/laravel)





Laravel renders pages through Blade layouts, so the snippet goes into the layout file that wraps your site. Read the site ID from `config/services.php` and `.env` so it stays out of the template and differs per environment.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Laravel [#add-the-snippet-to-laravel]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to `.env`:

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then register them in `config/services.php`:

    ```php filename="config/services.php"
    <?php

    return [
        // ... other services

        'rybbit' => [
            'instance_url' => env('RYBBIT_INSTANCE_URL', 'https://app.rybbit.io'),
            'site_id' => env('RYBBIT_SITE_ID'),
        ],
    ];
    ```

    Run `php artisan config:clear` if your configuration is cached, otherwise the new keys are not picked up.

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open the Blade layout that wraps your pages. In a default install this is `resources/views/layouts/app.blade.php`; Breeze and Jetstream also ship `resources/views/layouts/guest.blade.php`, and Inertia apps use `resources/views/app.blade.php`. Add the tag inside `<head>`:

    ```php filename="resources/views/layouts/app.blade.php"
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>{{ config('app.name', 'Laravel') }}</title>
        @vite(['resources/css/app.css', 'resources/js/app.js'])

        @production
            <script src="{{ config('services.rybbit.instance_url') }}/api/script.js?siteId={{ config('services.rybbit.site_id') }}" defer></script>
        @endproduction
    </head>
    ```

    `@production` only renders the tag when `APP_ENV=production`, so local development is not tracked. Drop the directive if you also want data from staging.

    If you have several layouts (for example `app` and `guest`), add the tag to each one, or move it into a partial such as `resources/views/partials/rybbit.blade.php` and `@include` it from every layout.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in production**: run `php artisan config:clear` and `php artisan view:clear` after changing `.env` or `config/services.php`; cached config and compiled views keep the old values.
* **Tag missing locally**: `@production` hides it unless `APP_ENV=production`. Set that temporarily to test, or remove the directive.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Leadpages (/zh/docs/guides/leadpages)





Every Leadpages page, site and pop-up has an **Analytics** tab in its builder settings with a **Head Section Tracking Code** field, and that is where the snippet goes. In the site builder the setting is site-wide, so one paste covers every page of the site; landing pages built on their own are tracked one page at a time.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Leadpages [#add-the-snippet-to-leadpages]

    1. Open the site or landing page in the builder.
    2. Click the **Settings** gear in the left-hand sidebar, then the **Analytics** tab.
    3. Paste the snippet into **Head Section Tracking Code**.
    4. Click **Save**, then **Update** to push the change to the published page.

    Repeat for each standalone landing page you want tracked. For sites, the code applies to every page in the site.

    Pop-ups have the same tracking code fields in their settings, but a pop-up shown on a page that already carries the snippet does not need its own copy.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: the page was saved but not updated. Click **Update** in the builder to republish.
* **Standalone pages missing**: tracking code on a site does not extend to landing pages published outside that site. Add the snippet to each one.
* **GA4 Measurement ID field**: the Analytics tab also has a field for a Google Analytics ID. That field is for GA4 only; the Rybbit snippet belongs in Head Section Tracking Code.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Lovable (/zh/docs/guides/lovable)





Lovable has no project setting for custom head code, so the snippet goes into the app's HTML head like any other code change: ask Lovable to add it in chat, or open the **Code** tab and edit the file yourself. Either way, the live app only picks it up after you publish the change.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Lovable [#add-the-snippet-to-lovable]

    <Tabs items="[&#x22;Ask Lovable&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of the app on every page. Do not remove any existing head tags.
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Check the diff Lovable shows: the tag belongs in the document head, not in a React component.
      </Tab>

      <Tab>
        Open the **Code** tab in the project toolbar (editing needs a paid plan; on the Free plan the editor is read-only). Which file holds the head depends on when the project was created:

        * **Projects created from May 13, 2026** use TanStack Start. Add the script to the `head()` of the root route in `src/routes/__root.tsx`; the `<HeadContent />` component already in that file renders it into the `<head>`:

        ```tsx title="src/routes/__root.tsx"
        export const Route = createRootRoute({
          head: () => ({
            scripts: [
              { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: true },
            ],
          }),
          component: RootComponent,
        });
        ```

        * **Older React + Vite projects** have a single `index.html` at the project root. Paste the snippet before `</head>`:

        ```html title="index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        Save with **Cmd+S** / **Ctrl+S**.
      </Tab>
    </Tabs>

    Then click **Publish** in the top right and choose **Publish changes**. Client-side route changes inside the app are tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live app still has no script**: Lovable does not push edits to the published app automatically. A dot on the **Publish** button means unpublished changes; open it and click **Publish changes**.
* **Free plan**: the Code tab is read-only, so use the chat prompt instead.
* **Script disappeared after a later prompt**: Lovable can rewrite the head when it regenerates the layout or upgrades the template. Add "keep the Rybbit script tag" to the project's Knowledge so future edits preserve it, and re-check the page source after big changes.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Magento (/zh/docs/guides/magento)





Magento Open Source and Adobe Commerce have a **Scripts and Style Sheets** field in the design configuration that prints HTML into the `<head>` of every storefront page, so no theme edits are needed. On 2.4.7 and later the checkout page runs under a strict Content Security Policy, so the tracker's host also needs a CSP whitelist entry before it loads there.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Magento [#add-the-snippet-to-magento]

    1. In the Admin sidebar, go to **Content > Design > Configuration**.
    2. Find the row for the scope you want to track (usually the store view) and click **Edit** in the **Action** column.
    3. Expand **HTML Head**.
    4. Paste the snippet at the end of **Scripts and Style Sheets** and click **Save Configuration**.
    5. Go to **System > Cache Management** and refresh the invalidated cache types, then purge Varnish or your CDN if you use one.

    #### Allow the tracker under CSP (2.4.7 and later) [#allow-the-tracker-under-csp-247-and-later]

    Magento 2.4.7 switched the checkout page (`checkout_index_index`) to CSP restrict mode; other storefront pages stay in report-only mode. Scripts from hosts that are not whitelisted are blocked on checkout, so add the tracker's host to `script-src` and `connect-src` with a `csp_whitelist.xml` in a module of your own (plus the usual `registration.php` and `etc/module.xml`):

    ```xml title="app/code/Vendor/Rybbit/etc/csp_whitelist.xml"
    <?xml version="1.0"?>
    <csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
        <policies>
            <policy id="script-src">
                <values>
                    <value id="rybbit" type="host">https://app.rybbit.io</value>
                </values>
            </policy>
            <policy id="connect-src">
                <values>
                    <value id="rybbit" type="host">https://app.rybbit.io</value>
                </values>
            </policy>
        </policies>
    </csp_whitelist>
    ```

    Run `bin/magento setup:upgrade` and flush the cache after adding the module. If you self-host Rybbit, whitelist your own instance's domain instead.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

The order success page renders `Magento_Checkout::success.phtml` through the `checkout.success` block, which reserves an `order.success.additional.info` container for extra content. Add a block to that container from the same module as the CSP whitelist; the block reads the order from the checkout session.

```php title="app/code/Vendor/Rybbit/Block/Purchase.php"
<?php
namespace Vendor\Rybbit\Block;

class Purchase extends \Magento\Checkout\Block\Onepage\Success
{
    public function getOrder(): \Magento\Sales\Model\Order
    {
        return $this->_checkoutSession->getLastRealOrder();
    }
}
```

```xml title="app/code/Vendor/Rybbit/view/frontend/layout/checkout_onepage_success.xml"
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="order.success.additional.info">
            <block class="Vendor\Rybbit\Block\Purchase" name="rybbit.purchase" template="Vendor_Rybbit::purchase.phtml" cacheable="false"/>
        </referenceContainer>
    </body>
</page>
```

```php title="app/code/Vendor/Rybbit/view/frontend/templates/purchase.phtml"
<?php
/** @var \Vendor\Rybbit\Block\Purchase $block */
$order = $block->getOrder();
if (!$order->getId()) {
    return;
}
$items = [];
foreach ($order->getAllVisibleItems() as $item) {
    $items[] = [
        'item_id'   => $item->getSku(),
        'item_name' => $item->getName(),
        'price'     => (float) $item->getPrice(),
        'quantity'  => (int) $item->getQtyOrdered(),
    ];
}
$purchase = [
    'transaction_id' => $order->getIncrementId(),
    'value'          => (float) $order->getGrandTotal(),
    'currency'       => $order->getOrderCurrencyCode(),
    'items'          => $items,
];
?>
<script>
document.addEventListener('DOMContentLoaded', function () {
    window.rybbit.event('purchase', <?= /* @noEscape */ json_encode($purchase) ?>);
});
</script>
```

The script waits for `DOMContentLoaded` because the tracker loads with `defer`. Event properties are limited to 2048 characters of JSON, so drop `items` for stores with large orders. `getTaxAmount()` and `getShippingAmount()` are available on the same order object if you want those too.

## Troubleshooting [#troubleshooting]

* **Snippet not in the page source**: design configuration is scoped, and a store-view row overrides the website and global rows. Edit the row that applies to the storefront you are checking, then flush the page cache and Varnish.
* **Tracked everywhere except checkout**: CSP restrict mode on `checkout_index_index` is blocking the script. Confirm the whitelist module is enabled and look for `Content-Security-Policy` errors naming `app.rybbit.io` in the browser console.
* **Purchase event missing**: `getLastRealOrder()` is only set in the session that placed the order, so reopening the success page later renders nothing.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Mintlify (/zh/docs/guides/mintlify)





Mintlify includes every `.js` file in your docs content directory on every page, so the snippet goes into a small JavaScript file that injects the tag.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Mintlify [#add-the-snippet-to-mintlify]

    Create a JavaScript file in your content directory, next to `docs.json` and your `.mdx` pages:

    ```javascript filename="rybbit.js"
    (function () {
      var el = document.createElement("script");
      el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
      el.defer = true;
      document.head.appendChild(el);
    })();
    ```

    Commit and deploy. Mintlify picks the file up automatically; there is nothing to register in `docs.json`. See Mintlify's [custom scripts](https://www.mintlify.com/docs/customize/custom-scripts) page for the current rules on file placement.

    To pass [script attributes](/docs/script#script-attributes) such as skip patterns, set them on the element before appending it:

    ```javascript filename="rybbit.js"
    el.setAttribute("data-skip-patterns", JSON.stringify(["/internal/**"]));
    ```

    <Callout type="info">
      Mintlify sites are single-page apps. Rybbit records client-side navigation as pageviews, so no extra code is needed.
    </Callout>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Mintlify pages are MDX, so you can attach handlers inline:

```mdx
<button
  onClick={() => window.rybbit?.event("download_clicked", { file: "getting-started.pdf" })}
>
  Download guide
</button>
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# MkDocs (/zh/docs/guides/mkdocs)





MkDocs has an `extra_javascript` setting in `mkdocs.yml` that adds a script tag to every page, which works with any theme. If you run Material for MkDocs you can instead extend the theme and place the tag in `<head>` yourself.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to MkDocs [#add-the-snippet-to-mkdocs]

    <Tabs items="[&#x22;mkdocs.yml&#x22;, &#x22;Material theme override&#x22;]">
      <Tab value="mkdocs.yml">
        Add the script URL to `extra_javascript`. MkDocs 1.5 and later accept the mapping form with a `defer` key:

        ```yaml title="mkdocs.yml"
        extra_javascript:
          - path: https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
            defer: true
        ```

        On MkDocs 1.4 or older, list the plain URL instead:

        ```yaml title="mkdocs.yml"
        extra_javascript:
          - https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
        ```

        Themes render `extra_javascript` entries at the end of `<body>` rather than in `<head>`; the script still loads on every page.
      </Tab>

      <Tab value="Material theme override">
        1. Point Material at an overrides directory in `mkdocs.yml`:

           ```yaml title="mkdocs.yml"
           theme:
             name: material
             custom_dir: overrides
           ```

        2. Create `overrides/main.html` and fill the `extrahead` block, which Material reserves for custom tags inside `<head>`:

           ```html title="overrides/main.html"
           {% extends "base.html" %}

           {% block extrahead %}
             <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
           {% endblock %}
           ```
      </Tab>
    </Tabs>

    Rebuild with `mkdocs build` and deploy the `site/` directory (or `mkdocs gh-deploy`).

    If Material's `navigation.instant` feature is on, page changes go through the History API and Rybbit records them as pageviews without extra code.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Config error on `defer`**: the `path` / `defer` mapping needs MkDocs 1.5+. Run `mkdocs --version` and either upgrade or use the plain URL form.
* **`main.html` has no effect**: the override only applies when `theme.custom_dir` is set and the file sits at `overrides/main.html`, relative to `mkdocs.yml`.
* **Local previews are tracked**: `mkdocs serve` renders the same config as `mkdocs build`. Use a second Rybbit site for local work if that matters.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Moodle (/zh/docs/guides/moodle)





Moodle has an **Additional HTML** admin setting that adds code to every page without touching the theme. Its **Within HEAD** field is where the snippet goes.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Moodle [#add-the-snippet-to-moodle]

    1. Log in as an administrator and go to **Site administration → Appearance → Additional HTML**.
    2. Paste the snippet into **Within HEAD**.
    3. Click **Save changes**.

    The snippet now loads on every page, including course pages, activities and the login page. Users must be able to reach `app.rybbit.io` from their browser; nothing is proxied through the Moodle server.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Moodle renders standard HTML, so `data-rybbit-event` attributes work anywhere you control markup, for example in a course page's HTML block or a label:

```html
<a href="/course/view.php?id=42" data-rybbit-event="course_open" data-rybbit-prop-course="42">
  Open course
</a>
```

For enrolment or completion events, call `window.rybbit.event()` from a small block of JavaScript placed in the **When BODY is closed** field of the same Additional HTML page.

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the page source**: Moodle caches rendered output. Go to **Site administration → Development → Purge caches** and reload.
* **Pages inside the mobile app are not tracked**: the Moodle app renders course content in its own WebView with its own pages; the Additional HTML setting only affects the web site.
* **Snippet pasted into Custom CSS**: theme settings such as Boost's **Raw SCSS** only accept styles. Use Additional HTML for script tags.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Nextra (/zh/docs/guides/nextra)





Nextra is a Next.js docs framework, so the snippet goes where it goes in any Next.js app: the root layout, rendered with `next/script`. Nextra 4 uses the App Router and `app/layout.jsx`; Nextra 3 uses the Pages Router and `pages/_app.jsx`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Nextra [#add-the-snippet-to-nextra]

    Use the `Script` component with `strategy="afterInteractive"` rather than a plain `<script>` tag; the `defer` attribute from the snippet is not needed.

    <Tabs items="[&#x22;Nextra 4 (App Router)&#x22;, &#x22;Nextra 3 (Pages Router)&#x22;]">
      <Tab value="Nextra 4 (App Router)">
        Add the `Script` next to the `Layout` in `app/layout.jsx` (or `.tsx`):

        ```jsx title="app/layout.jsx"
        import { Footer, Layout, Navbar } from "nextra-theme-docs";
        import { Head } from "nextra/components";
        import { getPageMap } from "nextra/page-map";
        import Script from "next/script";
        import "nextra-theme-docs/style.css";

        export default async function RootLayout({ children }) {
          return (
            <html lang="en" dir="ltr" suppressHydrationWarning>
              <Head />
              <body>
                <Layout
                  navbar={<Navbar logo={<b>My Docs</b>} />}
                  pageMap={await getPageMap()}
                  footer={<Footer>MIT {new Date().getFullYear()} © My Docs.</Footer>}
                >
                  {children}
                </Layout>
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```
      </Tab>

      <Tab value="Nextra 3 (Pages Router)">
        Create `pages/_app.jsx` if your project does not have one, and render the `Script` beside the page:

        ```jsx title="pages/_app.jsx"
        import Script from "next/script";

        export default function App({ Component, pageProps }) {
          return (
            <>
              <Component {...pageProps} />
              <Script
                src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </>
          );
        }
        ```

        Do not put the tag in the `head` option of `theme.config.jsx`: that option renders through `next/head`, and Next.js warns against loading scripts there.
      </Tab>
    </Tabs>

    Nextra navigates between pages client-side. Rybbit records those route changes as pageviews, so no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Only the docs pages are tracked**: in Nextra 4 the tag belongs in the root `app/layout.jsx`, not in a nested `app/docs/layout.jsx`, otherwise landing pages outside `docs/` are missed.
* **Upgrading from Nextra 3**: Nextra 4 dropped the Pages Router and `theme.config`. Move the `Script` from `pages/_app.jsx` to `app/layout.jsx` as part of the migration.
* **Proxying through your own domain**: see the [Next.js guide](/docs/guides/react/next-js) for rewrites; every endpoint must be rewritten, not just `script.js`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Odoo (/zh/docs/guides/odoo)





The Odoo Website app has a **Code Injection** setting in the website editor's theme panel with separate `<head>` and `</body>` fields that apply to every page of the website. The snippet goes in the `<head>` field. This works on Odoo Online, Odoo.sh and on-premise installs of Odoo 17 and 18.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Odoo [#add-the-snippet-to-odoo]

    1. Open your website's frontend and click **Edit** in the top bar.
    2. Switch to the **Theme** tab of the editor panel.
    3. Scroll to the **Advanced** section and, next to **Code Injection*&#x2A;, click &#x2A;*`<head>`**.
    4. Paste the snippet into the editor that opens and click **Save**.
    5. Click **Save** in the website editor to publish the change.

    The code is stored per website. If you run several websites from one Odoo database, switch website in the top bar and repeat the steps for each one.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Odoo eCommerce pages render standard HTML, so use `data-rybbit-event` attributes on any element you add in the editor, or call `window.rybbit.event()` from the `</body>` Code Injection field:

```html
<script>
  document.addEventListener("click", function (e) {
    if (e.target.closest("#add_to_cart")) {
      window.rybbit.event("add_to_cart");
    }
  });
</script>
```

The confirmation page is served at `/shop/confirmation`; a script that checks `window.location.pathname` there can send a `purchase` event once per order.

## Troubleshooting [#troubleshooting]

* **The `<head>` button is missing**: Code Injection requires the **Website → Editor and Designer** access right. An administrator can grant it under **Settings → Users & Companies → Users**, on the user's **Access Rights** tab.
* **Change is visible while logged in but not for visitors**: click **Save** in the editor after closing the code window; the code is published with the page.
* **Multiple websites**: the field applies only to the website currently selected in the editor.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Payload (/zh/docs/guides/payload)





Payload is a headless CMS that installs into a Next.js app: the admin panel lives in the `(payload)` route group and your site in the `(frontend)` route group. The tracking snippet goes into the frontend root layout, not into Payload's config or admin panel.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Payload [#add-the-snippet-to-payload]

    <Callout type="info">
      Payload has no template or head setting to paste into. Add the snippet to the root layout of the Next.js frontend that renders your site.
    </Callout>

    In both the `website` and `blank` templates created by `npx create-payload-app`, the frontend root layout is `src/app/(frontend)/layout.tsx`. Render `next/script` there, exactly as in the [Next.js guide](/docs/guides/react/next-js), so the script loads on every public route and stays out of the admin panel under `src/app/(payload)/`.

    ```tsx title="src/app/(frontend)/layout.tsx"
    import Script from "next/script";

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            {children}
            <Script
              src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    The script tracks client-side route changes automatically, so Next.js `<Link>` navigation between Payload pages and posts is counted without extra code.

    If your frontend is a separate app (Nuxt, Astro, SvelteKit) that fetches from Payload's REST or GraphQL API, follow that framework's guide instead: [Nuxt](/docs/guides/vue/nuxt), [Astro](/docs/guides/astro), [SvelteKit](/docs/guides/svelte/sveltekit), [Remix](/docs/guides/react/remix).
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live Preview counts as visits**: the admin panel's Live Preview loads your frontend in an iframe at the URL set in `admin.livePreview.url`. Editors' preview sessions are tracked like any other visitor. Point `livePreview.url` at a separate preview deployment registered as its own site in Rybbit, or skip the tag in preview builds.
* **Draft preview routes**: if you use the `website` template's `/next/preview` route or Next.js draft mode, those pages are also tracked. Add `data-skip-patterns='["/next/**"]'` to the script tag to exclude them.
* **Admin panel is not tracked**: `/admin` is rendered by the `(payload)` route group, which has its own layout without the snippet. Put the tag in the `(frontend)` layout only.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Phoenix (/zh/docs/guides/phoenix)





Phoenix renders every page inside the root layout, `lib/my_app_web/components/layouts/root.html.heex`, which owns the `<html>` and `<head>` tags, so the snippet goes there. Read the site ID from application config set in `config/runtime.exs`, so it comes from an environment variable at boot and stays out of the template.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Phoenix [#add-the-snippet-to-phoenix]

    #### Configure the site ID [#configure-the-site-id]

    `config/runtime.exs` runs when the app boots, including inside a release, so it is the right place to read environment variables. Add a `:rybbit` key for your app (replace `:my_app` with your OTP app name):

    ```elixir filename="config/runtime.exs"
    config :my_app, :rybbit,
      instance_url: System.get_env("RYBBIT_INSTANCE_URL", "https://app.rybbit.io"),
      site_id: System.get_env("RYBBIT_SITE_ID")
    ```

    Then set the variables where the app runs:

    ```bash
    export RYBBIT_INSTANCE_URL=https://app.rybbit.io
    export RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    #### Expose the config to the layout [#expose-the-config-to-the-layout]

    Templates in `lib/my_app_web/components/layouts/` are embedded into the `MyAppWeb.Layouts` module, so a function defined there is callable from `root.html.heex`. Add one that returns the config:

    ```elixir filename="lib/my_app_web/components/layouts.ex"
    defmodule MyAppWeb.Layouts do
      use MyAppWeb, :html

      embed_templates "layouts/*"

      def rybbit_config, do: Application.get_env(:my_app, :rybbit, [])
    end
    ```

    #### Add the tag to the root layout [#add-the-tag-to-the-root-layout]

    Open `lib/my_app_web/components/layouts/root.html.heex` and add the tag inside `<head>`, after the existing `app.css` and `app.js` tags:

    ```html filename="lib/my_app_web/components/layouts/root.html.heex"
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta name="csrf-token" content={get_csrf_token()} />
      <.live_title suffix=" · Phoenix Framework">{assigns[:page_title] || "MyApp"}</.live_title>
      <link phx-track-static rel="stylesheet" href={~p"/assets/app.css"} />
      <script defer phx-track-static type="text/javascript" src={~p"/assets/app.js"}></script>

      <script
        :if={rybbit_config()[:site_id]}
        src={"#{rybbit_config()[:instance_url]}/api/script.js?siteId=#{rybbit_config()[:site_id]}"}
        defer
      ></script>
    </head>
    ```

    The `:if` attribute skips the tag when `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.

    #### LiveView navigation [#liveview-navigation]

    `<.link navigate>`, `<.link patch>`, `push_navigate/2` and `push_patch/2` change the URL with `history.pushState` (or `replaceState` when `replace: true`) and keep the root layout, including its `<head>`, in place. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each live navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `phx:` event listener is needed. A regular `<.link href>` does a full page load, which the script also tracks.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `config/runtime.exs` is evaluated at boot, so restart the app or release after changing `RYBBIT_SITE_ID`. Check with `Application.get_env(:my_app, :rybbit)` in `iex -S mix`.
* **Content Security Policy**: if you set a `content-security-policy` header in a plug, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Podia (/zh/docs/guides/podia)





Podia has a **Third-party code** setting under **Settings > Analytics** that adds the snippet to every public page of your site, including checkout. Podia inserts custom code just before the closing `</body>` tag rather than in `<head>`; the Rybbit script loads with `defer` and works the same from either position.

<Callout type="warn">
  Third-party code is available on Podia's **Mover** and **Shaker** plans. On the free plan the Third-party code option is not shown.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Podia [#add-the-snippet-to-podia]

    1. From your home feed, click your site name and choose **Admin**.
    2. In the Admin sidebar, open **Settings > Analytics**.
    3. Click **Edit** next to **Third-party code**.
    4. Paste the snippet into the **Website tracking code** field.
    5. Click **Save**. The code is live as soon as it is saved; there is no separate publish step.

    The website tracking code runs on every public page of your site and on checkout pages. It does not run inside logged-in areas such as the customer dashboard, product viewer or community spaces.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Podia has a second field, **Conversion tracking code**, directly below the website tracking code. Code in that field runs only on the thank-you page after a purchase or membership signup, and Podia exposes the order as a `Podia.Conversion` object on that page (once per order; it is gone after a refresh).

Paste this into **Conversion tracking code** to send a `purchase` event with the order details:

```html
<script>
(function () {
  var c = window.Podia && window.Podia.Conversion;
  if (!c) return;
  var payload = {
    product: c.object.name,
    order_id: c.object.order_id,
    value: c.revenue,
    currency: c.currency
  };
  var start = Date.now();
  (function send() {
    if (window.rybbit && typeof window.rybbit.event === "function") {
      return window.rybbit.event("purchase", payload);
    }
    if (Date.now() - start < 8000) setTimeout(send, 150);
  })();
})();
</script>
```

The short polling loop is there because Podia runs the conversion code before the deferred tracking script has finished loading. `revenue` is `0` for free products and free membership plans, so filter on `value` in the dashboard if you only want paid orders.

## Troubleshooting [#troubleshooting]

* **No Third-party code option**: the site is on the free plan. Third-party code requires Mover or Shaker.
* **No pageviews while you test**: Podia does not output tracking code when you are logged in to your own Podia account. Test in a private window, or log out first.
* **Logged-in member pages are missing**: expected. Custom code runs only on public pages and checkout, not in the customer dashboard, product viewer or community.
* **Duplicate purchase events**: `Podia.Conversion` is only present on the first load of the thank-you page, so a refresh does not resend. If you see duplicates, make sure the event script is in Conversion tracking code only and not also in Website tracking code.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Preact (/zh/docs/guides/preact)





A Preact app scaffolded with `npm init preact` (or Vite's `preact` template) has a single `index.html` at the project root. Paste the snippet into its `<head>` and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Preact [#add-the-snippet-to-preact]

    Open `index.html` at the root of the project and paste the snippet inside `<head>`:

    ```html title="index.html"
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Vite + Preact</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/index.jsx"></script>
      </body>
    </html>
    ```

    Placing it before `</body>` also works; `<head>` lets it start loading sooner. Route changes made by `preact-iso`, `preact-router` or a similar router are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw.

```jsx title="src/components/SignupButton.jsx"
export function SignupButton() {
  const handleClick = () => {
    if (window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# PrestaShop (/zh/docs/guides/prestashop)





PrestaShop's back office has no built-in setting for custom `<head>` code, so the snippet goes in either through a header-injection module from the Addons marketplace or directly into your theme's `head.tpl`. Either way, clear the cache afterwards.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to PrestaShop [#add-the-snippet-to-prestashop]

    <Tabs items="[&#x22;Custom code module&#x22;, &#x22;Theme files&#x22;]">
      <Tab>
        1. In the back office, go to **Modules > Module Manager** (or **Module Catalog**) and install a module that injects custom HTML into the page header, for example a "Custom HTML" or "Header code" module from the [PrestaShop Addons marketplace](https://addons.prestashop.com/).
        2. Open the module's configuration, paste the snippet into its head / header code field, and save.
        3. Go to **Advanced Parameters > Performance** and click **Clear cache**.
      </Tab>

      <Tab>
        <Callout type="warn">
          Edit a child theme. Changes to the parent theme are lost on theme updates.
        </Callout>

        1. Over FTP/SFTP or a file manager, open `/themes/your-theme-name/templates/_partials/head.tpl`.
        2. Paste the snippet at the end of the file, before the closing `</head>` tag, and save.
        3. Go to **Advanced Parameters > Performance** and click **Clear cache**.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

Add this to your theme's `order-confirmation.tpl`, or output it from a module hooked to the order confirmation page. PrestaShop renders templates with Smarty, so the `$order` variables are filled in with the order data:

```html
{if isset($order)}
<script>
(function () {
  function waitForRybbit(callback, timeout) {
    var start = Date.now();
    (function check() {
      if (window.rybbit && typeof window.rybbit.event === 'function') {
        callback();
      } else if (Date.now() - start < timeout) {
        setTimeout(check, 100);
      }
    })();
  }

  waitForRybbit(function () {
    window.rybbit.event('purchase', {
      transaction_id: '{$order.details.reference}',
      value: {$order.totals.total.amount},
      currency: '{$order.totals.total.currency}'
    });
  }, 5000);
})();
</script>
{/if}
```

`waitForRybbit` polls until the tracking script from `head.tpl` has defined `window.rybbit`, so the event is not lost when the confirmation script runs first.

## Troubleshooting [#troubleshooting]

* **Script not on the page**: clear the cache under **Advanced Parameters > Performance**, and temporarily disable any JavaScript optimisation or combine/minify module.
* **Theme updates overwrite the snippet**: keep template edits in a child theme; parent-theme changes are lost on update.
* **Purchase event missing**: the `$order` Smarty variables differ between PrestaShop versions. Compare them with your version's `order-confirmation.tpl` and place a test order to confirm the event arrives.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Qwik (/zh/docs/guides/qwik)





A Qwik City app renders the whole document from `src/root.tsx`, which owns the `<head>` and `<body>` elements. Add the snippet to that `<head>` and it is on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Qwik [#add-the-snippet-to-qwik]

    Open `src/root.tsx` and add the tag inside `<head>`, after `<RouterHead />`:

    ```tsx title="src/root.tsx"
    import { component$ } from "@builder.io/qwik";
    import { QwikCityProvider, RouterOutlet } from "@builder.io/qwik-city";
    import { RouterHead } from "./components/router-head/router-head";

    import "./global.css";

    export default component$(() => {
      return (
        <QwikCityProvider>
          <head>
            <meta charset="utf-8" />
            <RouterHead />
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body lang="en">
            <RouterOutlet />
          </body>
        </QwikCityProvider>
      );
    });
    ```

    `src/components/router-head/router-head.tsx` renders per-route `head` exports (title, meta, links). Keep the Rybbit tag in `root.tsx` so it does not depend on any route's `head` export.

    Navigations through Qwik City's `<Link>` component are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a `$` event handler. Handlers only run in the browser, so `window` is always defined; guard against a blocked or still-loading script.

```tsx title="src/components/signup-button.tsx"
import { component$ } from "@builder.io/qwik";

export const SignupButton = component$(() => {
  return (
    <button
      onClick$={() => {
        if (window.rybbit) {
          window.rybbit.event("signup_click", { location: "hero" });
        }
      }}
    >
      Sign up
    </button>
  );
});
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Ruby on Rails (/zh/docs/guides/rails)





Rails wraps every page in `app/views/layouts/application.html.erb`, so the snippet goes into that layout's `<head>`. Read the site ID from a custom `config.x` setting fed by an environment variable, so the template stays free of hard-coded IDs and each environment can use its own site.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Ruby on Rails [#add-the-snippet-to-ruby-on-rails]

    #### Configure the site ID [#configure-the-site-id]

    Add the Rybbit values to your environment (`.env` if you use dotenv-rails, otherwise your host's environment settings):

    ```bash filename=".env"
    RYBBIT_INSTANCE_URL=https://app.rybbit.io
    RYBBIT_SITE_ID=YOUR_SITE_ID
    ```

    Then expose them through the `config.x` namespace in `config/application.rb`:

    ```ruby filename="config/application.rb"
    module MyApp
      class Application < Rails::Application
        # ... existing configuration

        config.x.rybbit.instance_url = ENV.fetch("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
        config.x.rybbit.site_id = ENV["RYBBIT_SITE_ID"]
      end
    end
    ```

    #### Add the tag to your layout [#add-the-tag-to-your-layout]

    Open `app/views/layouts/application.html.erb` and add the tag inside `<head>`, after the stylesheet and JavaScript tags:

    ```erb filename="app/views/layouts/application.html.erb"
    <head>
      <title><%= content_for(:title) || "MyApp" %></title>
      <meta name="viewport" content="width=device-width,initial-scale=1">
      <%= csrf_meta_tags %>
      <%= csp_meta_tag %>
      <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
      <%= javascript_importmap_tags %>

      <% if Rails.configuration.x.rybbit.site_id.present? %>
        <script src="<%= Rails.configuration.x.rybbit.instance_url %>/api/script.js?siteId=<%= Rails.configuration.x.rybbit.site_id %>" defer></script>
      <% end %>
    </head>
    ```

    The `if` guard skips the tag wherever `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.

    If you have more than one HTML layout (for example `application.html.erb` and `admin.html.erb`), add the tag to each, or move it into a partial such as `app/views/layouts/_rybbit.html.erb` and `<%= render "layouts/rybbit" %>` from every layout. Mailer layouts do not need it.

    #### Turbo and Hotwire [#turbo-and-hotwire]

    Turbo Drive replaces the page `<body>` on each visit, merges the `<head>`, and pushes the new URL with `history.pushState`. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so every Turbo visit is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `turbo:load` listener is needed. Because the script tag is in `<head>` and identical on every page, Turbo Drive keeps the existing tag instead of loading it again.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing**: `config/application.rb` is read once at boot, so restart the server after changing `RYBBIT_SITE_ID`. Check `Rails.configuration.x.rybbit.site_id` in `rails console` if the tag does not render.
* **Content Security Policy**: if you set a policy in `config/initializers/content_security_policy.rb`, add your Rybbit host to `script_src` and `connect_src`, or the browser blocks both the script and the `/api/track` requests. Alternatively [proxy the script](/docs/proxy-guide) through your own domain so no extra origin is needed.
* **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Replit (/zh/docs/guides/replit)





Replit has no publishing setting for custom head code, so the snippet goes into the app's HTML entry file: ask Agent to add it, or open the file in the workspace and paste it yourself. The change reaches the live URL only after you republish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Replit [#add-the-snippet-to-replit]

    <Tabs items="[&#x22;Ask Agent&#x22;, &#x22;Edit the code&#x22;]">
      <Tab>
        Paste this into the Agent chat, with your snippet in place of the placeholder:

        ```text
        Add this script tag to the <head> of the app's HTML entry file so it loads on every page. Keep all existing head tags.
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        Review the change before you approve it: the tag belongs in the HTML document, not in a React component or server file.
      </Tab>

      <Tab>
        Open the file that owns the `<head>` from the **Files** pane of the workspace:

        * Agent-built web apps are typically a Vite + React client with an Express server, and the HTML entry is `client/index.html`. Some projects keep it at `index.html` in the project root.
        * Next.js projects use `app/layout.tsx` with `next/script`, as in the [Next.js guide](/docs/guides/react/next-js).
        * Plain HTML projects (Static deployments): add the tag to every page, or to the shared template if you have one.

        Paste the snippet before `</head>`:

        ```html title="client/index.html"
        <head>
          <meta charset="UTF-8" />
          <title>My app</title>
          <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```
      </Tab>
    </Tabs>

    Then click **Publish** in the upper right (or **Republish** for an app that is already live) so a new release goes out at the same URL. In-app route changes are tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Live app has no script**: changes in the Project Editor do not replace the live release on their own. Test in Preview, then click **Republish**.
* **Agent rewrote the file**: a later request can regenerate `client/index.html`. Tell Agent to keep the Rybbit script when you ask for layout changes, and re-check the page source after large refactors.
* **Numbers differ from Replit's deployment analytics**: Replit counts requests at the server; Rybbit counts browser pageviews after ad blockers and bot filtering, so the two rarely match exactly.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Sanity (/zh/docs/guides/sanity)





Sanity is a headless CMS: your frontend queries content from the Content Lake and Sanity Studio is only the editing app. The tracking snippet therefore goes into the frontend that renders your site, not into Sanity.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Sanity [#add-the-snippet-to-sanity]

    <Callout type="info">
      Sanity has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Sanity.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Sanity frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby)
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Embedded Studio pageviews**: if Sanity Studio is mounted inside your frontend (for example at `/studio` in a Next.js app), the snippet in your root layout also runs there. Add `data-skip-patterns='["/studio/**"]'` to the script tag so editor sessions are not counted as visits.
* **Hosted Studio is not tracked**: a Studio deployed to `*.sanity.studio` is a separate app without the snippet, so time spent editing never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Shopify Hydrogen (/zh/docs/guides/shopify-hydrogen)





Hydrogen storefronts render the HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file's `Layout` component, and the tracker's host is added to the Content Security Policy that `app/entry.server.tsx` builds. This guide is for headless Hydrogen storefronts; for an Online Store theme, see the [Shopify guide](/docs/guides/shopify).

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Shopify Hydrogen [#add-the-snippet-to-shopify-hydrogen]

    Hydrogen ships with a nonce-based CSP, so a plain `<script>` tag without the nonce is blocked. Use Hydrogen's `Script` component, which adds the nonce for you.

    1. Open `app/root.tsx` and add the tag inside `<head>` of the `Layout` component:

    ```tsx title="app/root.tsx"
    import { Analytics, getShopAnalytics, Script, useNonce } from "@shopify/hydrogen";

    export function Layout({children}: {children?: React.ReactNode}) {
      const nonce = useNonce();

      return (
        <html lang="en">
          <head>
            <meta charSet="utf-8" />
            <meta name="viewport" content="width=device-width,initial-scale=1" />
            <Meta />
            <Links />
            <Script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer />
          </head>
          <body>
            {children}
            <ScrollRestoration nonce={nonce} />
            <Scripts nonce={nonce} />
          </body>
        </html>
      );
    }
    ```

    2. Open `app/entry.server.tsx` and allow the tracker's host in the CSP. Values you pass for `connectSrc` are merged with Hydrogen's defaults, but `scriptSrc` has no default to merge with (it falls back to `default-src`), so list Shopify's CDN alongside Rybbit:

    ```tsx title="app/entry.server.tsx"
    const {nonce, header, NonceProvider} = createContentSecurityPolicy({
      shop: {
        checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
        storeDomain: context.env.PUBLIC_STORE_DOMAIN,
      },
      scriptSrc: ["'self'", "https://cdn.shopify.com", "https://app.rybbit.io"],
      connectSrc: ["https://app.rybbit.io"],
    });
    ```

    `connect-src` lets the tracker post events; `script-src` is needed because features such as session replay load a second script from the same host at runtime. If you self-host Rybbit, use your instance's domain.

    Restart the dev server. Client-side navigation between routes is tracked automatically as pageviews. Projects created before Hydrogen moved to React Router import `Meta`, `Links` and `Scripts` from `@remix-run/react`; the edit is the same.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Hydrogen's `Analytics.Provider` already publishes storefront events (`product_viewed`, `product_added_to_cart`, `cart_updated` and others), so subscribe to them once in a small component instead of instrumenting each route.

```tsx title="app/components/RybbitAnalytics.tsx"
import { useAnalytics } from "@shopify/hydrogen";
import { useEffect } from "react";

export function RybbitAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register("Rybbit");

  useEffect(() => {
    subscribe("product_viewed", (data) => {
      const product = data.products[0];
      if (!product) return;
      window.rybbit?.event("view_item", {
        item_id: product.sku || product.variantId,
        item_name: product.title,
        item_variant: product.variantTitle,
        price: Number(product.price),
      });
    });
    subscribe("product_added_to_cart", (data) => {
      const line = data.currentLine;
      if (!line) return;
      window.rybbit?.event("add_to_cart", {
        item_id: line.merchandise.sku || line.merchandise.id,
        item_name: line.merchandise.product.title,
        price: Number(line.cost.totalAmount.amount),
        currency: line.cost.totalAmount.currencyCode,
        quantity: line.quantity,
      });
    });
    ready();
  }, []);

  return null;
}
```

Render `<RybbitAnalytics />` inside `<Analytics.Provider>` in the `App` component of `app/root.tsx`. Declare `window.rybbit` with the type from [Track events](/docs/track-events#typescript-support) so TypeScript accepts the calls. Skip `page_viewed`: the tracker records route changes itself.

<Callout type="info">
  Checkout does not run in Hydrogen. Track purchases with the custom web pixel from the [Shopify guide](/docs/guides/shopify#purchase), which works for Hydrogen and Online Store checkouts alike.
</Callout>

## Troubleshooting [#troubleshooting]

* **`Refused to load the script` in the console**: the CSP change in `entry.server.tsx` is missing or the dev server was not restarted. The nonce alone is not enough once session replay loads its second script.
* **`POST /api/track` blocked**: `connectSrc` does not include the tracker's host. Self-hosted instances need their own domain here.
* **Early events dropped**: on a cold load a subscription can fire before the deferred script runs. The optional chaining above skips those; wrap the calls in `window.rybbit.onReady()` if you need every one.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Shopify (/zh/docs/guides/shopify)





On Shopify the snippet goes into your theme's `theme.liquid` layout, which wraps every storefront page. Checkout runs on Shopify's own sandboxed pages, so purchases are tracked separately through a custom web pixel.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Shopify [#add-the-snippet-to-shopify]

    1. In Shopify admin, go to **Online Store > Themes**.
    2. On your current theme, click the &#x2A;*...** button next to **Customize** and choose **Edit code**.
    3. Open `theme.liquid` in the **Layout** folder.
    4. Paste the snippet just before the closing `</head>` tag and click **Save**.

    Theme updates can overwrite `theme.liquid`. Shopify has no child-theme system, so after updating a purchased theme, re-add the snippet.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Storefront templates can call `window.rybbit.event()` directly. Wrap the calls in a `DOMContentLoaded` listener because the tracking script is loaded with `defer`, and divide Liquid prices by 100 because they are in cents.

<Callout type="warn">
  Back up your theme before editing code. Liquid object names such as `product.selected_or_first_available_variant` and the form selectors below vary between themes, so adjust them to match yours.
</Callout>

#### View product [#view-product]

Add to your main product template (`sections/main-product.liquid` or `templates/product.liquid`, depending on the theme):

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var variant = {{ product.selected_or_first_available_variant | json }};
  window.rybbit.event('view_item', {
    item_id: variant.sku || variant.id,
    item_name: {{ product.title | json }},
    item_variant: variant.title === 'Default Title' ? null : variant.title,
    price: variant.price / 100,
    currency: {{ cart.currency.iso_code | json }}
  });
});
</script>
```

#### Add to cart [#add-to-cart]

In the same template, listen on the product form. Themes with an AJAX cart drawer usually fire their own JavaScript event after an item is added; hooking that is more reliable than the form submit.

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var form = document.querySelector('form[action="/cart/add"]');
  if (!form) return;
  form.addEventListener('submit', function () {
    var variant = {{ product.selected_or_first_available_variant | json }};
    var qty = form.querySelector('[name="quantity"]');
    window.rybbit.event('add_to_cart', {
      item_id: variant.sku || variant.id,
      item_name: {{ product.title | json }},
      price: variant.price / 100,
      currency: {{ cart.currency.iso_code | json }},
      quantity: qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1
    });
  });
});
</script>
```

#### Begin checkout [#begin-checkout]

Add to your cart template (`sections/main-cart-items.liquid` or `templates/cart.liquid`) to track clicks on the checkout button:

```liquid
<script>
document.addEventListener('DOMContentLoaded', function () {
  var button = document.querySelector('[name="checkout"]');
  if (!button) return;
  button.addEventListener('click', function () {
    var cart = {{ cart | json }};
    window.rybbit.event('begin_checkout', {
      currency: cart.currency,
      value: cart.total_price / 100,
      items: cart.items.map(function (item) {
        return { item_id: item.sku || item.variant_id, quantity: item.quantity, price: item.final_price / 100 };
      })
    });
  });
});
</script>
```

Event properties are limited to 2048 characters of serialised JSON and larger payloads are rejected, not truncated. Keep `items` compact, or send only the totals for large carts.

#### Purchase [#purchase]

Checkout and the order status page do not load your theme, and the old **Order status page > Additional scripts** field is deprecated: view-only since August 28, 2025, with non-Plus stores required to migrate by August 26, 2026. Track purchases with a custom web pixel from [Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations) instead.

Pixels run in a sandbox with no access to `window.rybbit`, so the pixel posts the event straight to Rybbit's track endpoint.

1. In Shopify admin, go to **Settings > Customer events**.
2. Click **Add custom pixel**, name it `Rybbit`, and click **Add pixel**.
3. Paste the code below, replace `YOUR_SITE_ID`, then **Save** and **Connect** the pixel.

```javascript
analytics.subscribe("checkout_completed", (event) => {
  const checkout = event.data.checkout;
  const items = (checkout.lineItems || []).map((li) => ({
    id: li.variant?.sku || li.variant?.id,
    qty: li.quantity,
    price: li.variant?.price?.amount,
  }));

  fetch("https://app.rybbit.io/api/track", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    keepalive: true,
    body: JSON.stringify({
      type: "custom_event",
      site_id: "YOUR_SITE_ID",
      event_name: "purchase",
      // properties must be a JSON string of at most 2048 characters
      properties: JSON.stringify({
        transaction_id: checkout.order?.id || checkout.token,
        value: checkout.totalPrice?.amount,
        currency: checkout.currencyCode,
        items,
      }),
    }),
  });
});
```

`checkout_completed` fires once per placed order. The same [Customer Events](https://shopify.dev/docs/api/customer-events) API also exposes `product_added_to_cart` and `checkout_started`, so you can move add-to-cart and begin-checkout into the pixel too if theme code is unreliable on your store.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# SolidJS (/zh/docs/guides/solid)





A client-side Solid app built with Vite has a single `index.html` at the project root; a SolidStart app renders its document from `src/entry-server.tsx`. Paste the snippet into the `<head>` of whichever file your project has and it loads on every route.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to SolidJS [#add-the-snippet-to-solidjs]

    <Tabs items="[&#x22;Vite&#x22;, &#x22;SolidStart&#x22;]">
      <Tab value="Vite">
        Open `index.html` at the root of the project (the file `npm create solid@latest` generates for the vanilla templates) and paste the snippet inside `<head>`:

        ```html title="index.html"
        <!DOCTYPE html>
        <html lang="en">
          <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            <title>Solid App</title>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
          </head>
          <body>
            <div id="root"></div>
            <script src="/src/index.tsx" type="module"></script>
          </body>
        </html>
        ```
      </Tab>

      <Tab value="SolidStart">
        SolidStart has no `index.html`. The `<html>` document is the `document` prop of `<StartServer>` in `src/entry-server.tsx`; `src/app.tsx` only renders the router inside it. Add the tag to `<head>` next to `{assets}`:

        ```tsx title="src/entry-server.tsx"
        // @refresh reload
        import { createHandler, StartServer } from "@solidjs/start/server";

        export default createHandler(() => (
          <StartServer
            document={({ assets, children, scripts }) => (
              <html lang="en">
                <head>
                  <meta charset="utf-8" />
                  <meta name="viewport" content="width=device-width, initial-scale=1" />
                  <link rel="icon" href="/favicon.ico" />
                  <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
                  {assets}
                </head>
                <body>
                  <div id="app">{children}</div>
                  {scripts}
                </body>
              </html>
            )}
          />
        ));
        ```

        Restart the dev server after the change.
      </Tab>
    </Tabs>

    Route changes made by `@solidjs/router` (including SolidStart's file routes) are tracked automatically as pageviews.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw; in SolidStart the guard also covers server rendering.

```tsx title="src/components/SignupButton.tsx"
export default function SignupButton() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Squarespace (/zh/docs/guides/squarespace)





Squarespace injects custom HTML into every page through its **Code Injection** panel, so no template edits are needed.

<Callout type="warn">
  Code Injection is available on the **Business** and **Commerce** plans. It is not available on the Personal plan.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Squarespace [#add-the-snippet-to-squarespace]

    1. From the Home Menu, open **Settings**.
    2. Open **Website**, then **Code Injection** (listed under **Advanced** or **Developer** depending on your Squarespace version).
    3. Paste the snippet into the **Header** field. The script is deferred, so it does not delay page rendering.
    4. Click **Save** at the top of the panel.

    The **Footer** field also works and loads the script on every page. Leave the **Lock Page** and **Order Confirmation Page** fields alone; they only apply to those single pages.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Code Injection is missing from Settings**: the site is on the Personal plan. Upgrade to Business or Commerce.
* **Only the checkout is tracked**: the snippet was pasted into **Order Confirmation Page** instead of **Header** or **Footer**.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Starlight (/zh/docs/guides/starlight)





Starlight, the documentation theme for Astro, has a `head` option in its integration config that adds tags to every page. The snippet goes there, in `astro.config.mjs`, so no component overrides are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Starlight [#add-the-snippet-to-starlight]

    Open `astro.config.mjs` at the root of your project and add a `script` entry to the `head` array of the `starlight()` integration:

    ```javascript title="astro.config.mjs"
    import { defineConfig } from "astro/config";
    import starlight from "@astrojs/starlight";

    export default defineConfig({
      integrations: [
        starlight({
          title: "My Docs",
          head: [
            {
              tag: "script",
              attrs: {
                src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                defer: true,
              },
            },
          ],
        }),
      ],
    });
    ```

    Each `head` entry becomes an HTML element with the given attributes; `defer: true` renders as a boolean attribute. Rebuild with `npm run build` and deploy the `dist/` directory.

    <Callout type="info">
      Entries in `head` are written to the page as-is and skip Astro's script bundling, which is what you want for a remote tracker. Only override the `Head` component if you need to import a local asset.
    </Callout>

    Starlight serves each page as a full document, so every navigation is a normal pageview and no route-change handling is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Local previews are tracked**: `head` applies to `astro dev` as well as `astro build`. Read the site ID from an environment variable that only your deploy sets (`process.env.RYBBIT_SITE_ID`) and push the entry only when it is present, or keep a separate site in Rybbit for development.
* **Tag missing after editing the config**: the dev server restarts itself when `astro.config.mjs` changes, but a deployed site needs a fresh build.
* **Head component override**: if your project already overrides Starlight's `Head` component, make sure it still renders the default head (the override docs show how), otherwise config `head` entries are dropped with it.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Statamic (/zh/docs/guides/statamic)





Statamic wraps every template in a layout, and a fresh install uses `resources/views/layout.antlers.html` by default. The snippet goes in that layout's `<head>`, so it loads on every page without touching individual templates.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Statamic [#add-the-snippet-to-statamic]

    1. Open `resources/views/layout.antlers.html`.
    2. Add the tag before `</head>`:

    ```html title="resources/views/layout.antlers.html"
    <!doctype html>
    <html lang="{{ site:short_locale }}">
    <head>
        <meta charset="utf-8">
        <title>{{ title }} | {{ site:name }}</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        {{ template_content }}
    </body>
    </html>
    ```

    3. Save. Templates rendered through this layout (`{{ template_content }}`) now include the script.

    If an entry or collection sets a different `layout` field, add the tag to that layout file too, or move it into a partial such as `resources/views/partials/rybbit.antlers.html` and `{{ partial:rybbit }}` it from each layout. If your views use Blade (`layout.blade.php`), the same tag goes in the same place.

    To keep the site ID out of version control, put it in `.env` as `RYBBIT_SITE_ID` and use `{{ config:services:rybbit:site_id }}` after adding a `rybbit` entry to `config/services.php`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Static caching**: with `half` or `full` static caching enabled in `config/statamic/static_caching.php`, run `php please static:clear` after editing the layout, otherwise cached pages keep the old head.
* **Live Preview counts as visits**: the control panel's Live Preview renders your entry in an iframe at its real URL with a `token` query parameter. Editors' previews are tracked like any other visit, so check analytics from the live site rather than the control panel.
* **Control panel is not tracked**: `/cp` uses Statamic's own views, so the snippet never runs there.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Storyblok (/zh/docs/guides/storyblok)





Storyblok is a headless CMS: it stores content and delivers it through its APIs, while your frontend renders the pages. The tracking snippet therefore goes into the frontend's root layout, not into Storyblok.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Storyblok [#add-the-snippet-to-storyblok]

    <Callout type="info">
      Storyblok has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Storyblok.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Remix](/docs/guides/react/remix)
        * [Gatsby](/docs/guides/react/gatsby)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>

    The script tracks client-side route changes automatically, so navigation between stories in any of these frameworks is counted without extra code.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Visual Editor previews count as visits**: the Visual Editor loads your frontend in an iframe at the **Preview URL** set under **Settings > Visual Editor**, appending `_storyblok` and `_storyblok_tk[...]` query parameters. Editors' preview sessions are tracked like real visitors. Point the Preview URL at a separate preview deployment registered as its own site in Rybbit, or leave the tag out of builds that use the preview token.
* **Preview parameters in tracked URLs**: if the same deployment serves both the live site and the Visual Editor, the `_storyblok` parameters show up in tracked page URLs. Add `data-track-query="false"` to the script tag to drop query strings.
* **The Storyblok app is not tracked**: the snippet only runs in your frontend, so time spent in `app.storyblok.com` never appears in Rybbit.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Strapi (/zh/docs/guides/strapi)





Strapi is a headless CMS: it exposes your content over a REST or GraphQL API and does not render your website. The tracking snippet therefore goes into the frontend that consumes the Strapi API, not into Strapi.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Strapi [#add-the-snippet-to-strapi]

    <Callout type="info">
      Strapi has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Strapi.
    </Callout>

    <Tabs items="[&#x22;Next.js&#x22;, &#x22;Nuxt&#x22;, &#x22;Other frontends&#x22;]">
      <Tab>
        Next.js is the most common Strapi frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).
      </Tab>

      <Tab>
        Nuxt is a popular Strapi frontend. Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).
      </Tab>

      <Tab>
        * [Gatsby](/docs/guides/react/gatsby)
        * [Remix](/docs/guides/react/remix)
        * [Vite + React](/docs/guides/react/vite-cra)
        * [Vite + Vue](/docs/guides/vue/vite)
        * [Astro](/docs/guides/astro)
        * [SvelteKit](/docs/guides/svelte/sveltekit)
        * [Angular](/docs/guides/angular)
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **The admin panel is not tracked**: the Strapi admin at `/admin` is served by the Strapi server, not by your frontend, so it never loads the snippet. Content editors' activity does not appear in Rybbit, which is usually what you want.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# systeme.io (/zh/docs/guides/systeme-io)





systeme.io has an account-wide **Tracking code** setting under **Settings > Sales Funnels** that adds code to every funnel page, plus a per-page **Tracking** section with a header field in the page editor. Use the account-wide setting unless you only want to track certain pages.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to systeme.io [#add-the-snippet-to-systemeio]

    <Tabs items="[&#x22;All funnels&#x22;, &#x22;One page&#x22;]">
      <Tab>
        1. Click your **profile picture** in the top-right corner and choose **Settings**.
        2. Select **Sales Funnels** in the left menu.
        3. Paste the snippet into the **Tracking code** box and click **Save**.

        The code is added to every page in every funnel on the account.
      </Tab>

      <Tab>
        1. Open the funnel, select the page in the list on the left and click **Edit page**.
        2. Click **Settings** in the upper-left corner of the editor and scroll to the **Tracking** section.
        3. Paste the snippet into the **header** field (the one for code that belongs between `<head>` and `</head>`).
        4. Save the page.
      </Tab>
    </Tabs>

    Paste only the `<script>` tag. systeme.io asks that custom code never include `<head>`, `<body>` or `<html>` tags of its own.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Duplicate pageviews**: the snippet is in both the account-wide Tracking code and a page's Tracking section. Keep one.
* **Not visible in preview**: custom code runs on the live page only. Open the published funnel URL to test.
* **Pages outside funnels**: the Sales Funnels tracking code covers funnel pages. Blog and course pages have their own settings, so add the snippet there if you want that traffic in the same site.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Tauri (/zh/docs/guides/tauri)





Tauri v2 bundles your frontend into the app and serves it to the system webview. Install the `@rybbit/js` SDK in the frontend (or put the snippet in its `index.html`), then allow `https://app.rybbit.io` in the `app.security.csp` block of `src-tauri/tauri.conf.json`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Tauri [#add-the-snippet-to-tauri]

    <Callout type="info">
      Tauri's security guide advises against loading remote scripts such as CDN-hosted files. The SDK keeps all executable code inside the bundle, so it is the recommended method.
    </Callout>

    <Tabs items="[&#x22;@rybbit/js SDK&#x22;, &#x22;Script tag&#x22;]">
      <Tab>
        1. Install the package in your frontend project:

        ```bash
        npm install @rybbit/js
        ```

        2. Initialise it once in the frontend entry file (`src/main.ts` or equivalent):

        ```ts title="src/main.ts"
        import rybbit from "@rybbit/js";

        await rybbit.init({
          analyticsHost: "https://app.rybbit.io/api",
          siteId: "YOUR_SITE_ID",
        });
        ```

        3. Allow the analytics host in `connect-src`. Keep `ipc:` and `http://ipc.localhost`, which Tauri needs for frontend-to-Rust calls:

        ```json title="src-tauri/tauri.conf.json"
        {
          "app": {
            "security": {
              "csp": {
                "default-src": "'self'",
                "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]
              }
            }
          }
        }
        ```
      </Tab>

      <Tab>
        1. Paste the snippet into the `<head>` of your frontend's `index.html`:

        ```html title="index.html"
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        ```

        2. Allow the host in both `script-src` and `connect-src`:

        ```json title="src-tauri/tauri.conf.json"
        {
          "app": {
            "security": {
              "csp": {
                "default-src": "'self'",
                "script-src": ["'self'", "https://app.rybbit.io"],
                "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    If `app.security.csp` is unset, Tauri applies no CSP and neither change is needed. Route changes inside the app are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Works in `tauri dev` but not in the built app on macOS, Linux or iOS**: in development the frontend is served from your dev server (`http://localhost:1420` by default), which is a normal http origin. Production builds serve it from `http://tauri.localhost` on Windows and Android but from the custom scheme `tauri://localhost` on macOS, Linux and iOS. Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so requests from `tauri://localhost` are blocked by the webview. On Windows and Android, `app.windows[].useHttpsScheme: true` switches the origin to `https://tauri.localhost`; both forms work.
* **CSP violation in the webview console**: the message names the blocked directive. Add `https://app.rybbit.io` there; the SDK only needs `connect-src`, the script tag also needs `script-src`.
* **Object vs string CSP**: `app.security.csp` accepts either a single policy string or the object form shown above. Do not mix the two.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Teachable (/zh/docs/guides/teachable)





Teachable adds tracking scripts through **Code Snippets** in the school admin, where the **Head Code Snippets** section places code inside the `<head>` of every page of your school. Code Snippets are available on the Builder plan and above.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Teachable [#add-the-snippet-to-teachable]

    1. In the school admin, go to **Site > Code Snippets**.
    2. Paste the snippet into the **Head Code Snippets** section, which applies to all pages and all users.
    3. Click **Save**.

    The **Logged In Snippets** and **Logged Out Snippets** sections restrict code to one audience. Leave them empty for Rybbit so students and prospects are tracked alike; if you only want to measure the public site, use **Logged Out Snippets** instead of the head section.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Code Snippets is missing from the Site menu**: it needs the Builder plan or higher. Schools on lower plans cannot add custom scripts.
* **Checkout and login pages are not tracked**: head code snippets do not apply to SSO-based login or checkout pages served from `sso.teachable.com`. Pages on your school domain, including the course area, are covered.
* **Snippet pasted into a lesson's Custom HTML block**: that block only affects one lesson. Use **Code Snippets** for site-wide tracking.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Thinkific (/zh/docs/guides/thinkific)





Thinkific adds custom scripts through the **Site Footer Code** field under **Settings > Code & Analytics**. The code runs at the bottom of every page, including the Course Player, and editing it is available on paid plans (Basic or higher). Placing the snippet in the footer rather than the head is fine: it loads with `defer`, so timing is the same.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Thinkific [#add-the-snippet-to-thinkific]

    1. In the admin dashboard, go to **Settings** and open the **Code & Analytics** tab.
    2. Paste the snippet into **Site Footer Code**.
    3. Save.

    See Thinkific's [Site Footer Code](https://support.thinkific.com/hc/en-us/articles/360030724953-Site-Footer-Code) article for the field's current limits. Lesson changes inside the Course Player happen without a page reload; Rybbit tracks them as pageviews automatically as the URL changes.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Field is read-only or missing**: editing Site Footer Code needs a paid plan (Basic or higher).
* **Checkout is not tracked**: Site Footer Code does not run on Performance Checkout pages, so purchases complete outside Rybbit's view. Track the enrolment from the first page a student lands on after checkout, or use a webhook on your side.
* **Community pages are not tracked**: pages where students post and comment, and direct-messaging pages, are excluded from Site Footer Code by default.
* **Per-page footer code**: individual site pages also accept footer code in their page settings. Keep the site-wide field as the single place for the snippet so pages are not tracked twice.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# ThriveCart (/zh/docs/guides/thrivecart)





ThriveCart lets you add custom scripts to each checkout page, and its success page is where the purchase event goes. ThriveCart strips `data-*` attributes from script tags, so the site ID must travel in the script URL, as it does in the snippet below.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to ThriveCart [#add-the-snippet-to-thrivecart]

    1. In your ThriveCart dashboard, open the checkout page you want to track.
    2. Open **Settings > Tracking**, the custom scripts section.
    3. Paste the snippet into the header scripts field and save.

    Repeat for each checkout page. If checkout runs on a subdomain such as `sales.yourdomain.com` and your main site uses the same site ID, both are tracked as one site, so funnels can follow a visitor from your site through to the purchase.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Purchase [#purchase]

ThriveCart also interferes with how inline events fire, so the success-page script below loads the tracker itself if it is missing, waits for it, and uses `sessionStorage` to send the event once per browser session even if the visitor refreshes or navigates back.

Add it to the checkout's **success page** and fill in the values at the top:

```html
<script>
(function () {
  var EVENT_NAME = "purchase";
  var PAYLOAD = { content_name: "Your Product Name", value: 97.0, currency: "USD" };
  var SITE_ID = "YOUR_SITE_ID";
  var SCRIPT_SRC = "https://app.rybbit.io/api/script.js?siteId=" + SITE_ID;

  // Send once per session, even on refresh or back navigation
  var SENT_KEY = "rybbit_" + EVENT_NAME + "_sent_v1";
  try {
    if (sessionStorage.getItem(SENT_KEY) === "1") return;
    sessionStorage.setItem(SENT_KEY, "1");
  } catch (e) {}

  function isReady() {
    return window.rybbit && typeof window.rybbit.event === "function";
  }
  function send() {
    window.rybbit.event(EVENT_NAME, PAYLOAD);
  }
  function waitThenSend(timeoutMs) {
    var start = Date.now();
    (function check() {
      if (isReady()) return send();
      if (Date.now() - start < timeoutMs) setTimeout(check, 150);
    })();
  }

  if (isReady()) return send();
  if (!document.querySelector('script[src="' + SCRIPT_SRC + '"]')) {
    var s = document.createElement("script");
    s.src = SCRIPT_SRC;
    s.defer = true;
    document.head.appendChild(s);
  }
  waitThenSend(8000);
})();
</script>
```

* `EVENT_NAME`: the event name, for example `purchase` or `checkout_complete`.
* `PAYLOAD`: `content_name` (product name), `value` (amount) and `currency` (`USD`, `GBP`, `EUR` and so on).
* `SITE_ID`: your Rybbit site ID.

Selling several products? The payload is fixed per page, so use a separate success page per product, or fill `PAYLOAD` from ThriveCart's dynamic variables where they are available.

## Troubleshooting [#troubleshooting]

* **Script attributes are stripped**: ThriveCart removes `data-*` attributes, so [script attributes](/docs/script#script-attributes) such as `data-skip-patterns` do not work here. Keep the site ID in the URL.
* **Duplicate purchase events**: the script is guarded by `sessionStorage`. If you still see duplicates, make sure the event script is on the success page only once, and clear session storage before testing again.
* **Script blocked**: if `script.js` never loads, try the footer scripts field instead of the header, or ask ThriveCart support to confirm custom scripts are enabled on your account.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# TYPO3 (/zh/docs/guides/typo3)





TYPO3 sitepackages build the page `<head>` from TypoScript rather than an HTML template, so the snippet is added as a `page.includeJS` entry in your sitepackage's `setup.typoscript`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to TYPO3 [#add-the-snippet-to-typo3]

    1. Open your main TypoScript setup file, usually `<sitepackage>/Configuration/TypoScript/setup.typoscript`. It is the file that already contains `page = PAGE`. The same TypoScript can also live in a TypoScript record in the backend.

    2. Add the script to the `page` object:

       ```
       page = PAGE
       page {
         includeJS {
           rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
           rybbit.defer = 1
         }
       }
       ```

       Because the Site ID is part of the URL, no `data-*` attribute is needed, so this works on every supported TYPO3 version. Per-include attributes on `includeJS` only exist in TYPO3 12.1+.

    3. To track production only, wrap the include in an `applicationContext` condition:

       ```
       [applicationContext == "Production"]
       page.includeJS.rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
       page.includeJS.rybbit.defer = 1
       [END]
       ```

    4. Optionally keep the Site ID and instance URL in `constants.typoscript` (or a TypoScript record) so the setup file can be committed without site-specific values:

       ```
       # constants.typoscript
       rybbit {
         host = https://app.rybbit.io
         siteId = YOUR_SITE_ID
       }

       # setup.typoscript
       page.includeJS.rybbit = {$rybbit.host}/api/script.js?siteId={$rybbit.siteId}
       page.includeJS.rybbit.defer = 1
       ```

    5. Deploy the sitepackage, or set `applicationContext` accordingly, and flush the TYPO3 caches.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Script not in the page source**: TYPO3 caches rendered pages. Flush caches from the backend toolbar or with `vendor/bin/typo3 cache:flush` after changing TypoScript.
* **Wrong TypoScript file**: if several files define `page`, check the resulting `page.includeJS` in the TypoScript object browser in the backend to see which definition wins.
* **Condition never matches**: the `applicationContext` is set through the `TYPO3_CONTEXT` environment variable. If it is unset, TYPO3 runs as `Production` and the script loads everywhere.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Umbraco (/zh/docs/guides/umbraco)





Umbraco renders pages with Razor templates stored as `.cshtml` files in the `Views` folder and edited in the backoffice under **Settings > Templates**. A fresh install has no templates until you create one, so the snippet goes into the master (layout) template that your page templates set as their `Layout`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Umbraco [#add-the-snippet-to-umbraco]

    1. In the backoffice, open the **Settings** section and expand **Templates**.
    2. Open the master template that the other templates use as their layout (named `Master&#x60; in Umbraco's own tutorial). If you have none yet, click &#x2A;*...** next to **Templates**, choose **Create**, and move the shared `<html>`, `<head>` and `<body>` markup into it.
    3. Add the tag before `</head>` and click **Save**:

    ```razor title="Views/Master.cshtml"
    @using Umbraco.Cms.Web.Common.PublishedModels;
    @inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
    @{
        Layout = null;
    }
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8" />
        <title>@Model.Name</title>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    </head>
    <body>
        @RenderBody()
    </body>
    </html>
    ```

    4. Check that each page template points at it, for example `Layout = "Master.cshtml";`. Templates with `Layout = null;` render their own `<head>` and need the tag added directly.

    Saving in the backoffice writes the same file to `Views/Master.cshtml` in the project, so you can also edit it in your IDE and commit it.

    To keep the site ID out of the template, put it in `appsettings.json` and read it with `@Configuration["Rybbit:SiteId"]` after injecting `IConfiguration`.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Change not visible**: Razor views are compiled on first request; if you edited the file outside the backoffice on a published site, restart the app or redeploy. Also clear any output cache or CDN in front of the site.
* **Preview counts as visits**: the backoffice **Preview** button renders your template with unpublished content, so editors' previews are tracked like any other visit. Wrap the tag in `@if (!UmbracoContext.InPreviewMode) { ... }` to leave them out.
* **Backoffice is not tracked**: `/umbraco` is a separate app that does not use your templates, so editing time never appears in Rybbit.
* **Several master templates**: a multi-site install with one layout per site needs the tag in each, or in a partial view rendered from every layout with `@await Html.PartialAsync("Rybbit")`.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Unbounce (/zh/docs/guides/unbounce)





Unbounce's **Script Manager** applies a script to every page on a domain, including pages you publish later, so that is where the snippet goes. If you only want to track a single Classic Builder page, the page-level **Javascripts** dialog works too.

<Callout type="warn">
  Custom scripts and pixels are not available on the Starter plan; you need Build or higher. Script Manager also requires a connected custom domain: it does not apply to pages on the `unbouncepages.com` test domain.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Unbounce [#add-the-snippet-to-unbounce]

    <Tabs items="[&#x22;Script Manager&#x22;, &#x22;Classic Builder page&#x22;]">
      <Tab>
        1. In the left menu, click **Settings**, then **Script Manager**.
        2. Click **Add a Script**, choose **Custom Script**, give it a name and click **Add Script Details**.
        3. Set **Placement** to **Head** and **Included on** to **All** (main pages and confirmation dialogs).
        4. Paste the snippet into the editor.
        5. Tick the domain(s) the script should apply to on the right, then click **Save Changes**.

        The script is added to every page on those domains and to new pages published there later. If a page does not pick it up, republish that page.
      </Tab>

      <Tab>
        1. Open the page in the Classic Builder and click **Javascripts** in the bottom-left corner.
        2. Give the script a name and set **Placement** to **Head**.
        3. Paste the snippet and click **Done**.
        4. **Save**, then **Publish** (or **Republish**) the page. Custom scripts do not run in the builder or in Preview, only on the published page.

        Smart Builder pages have no page-level script dialog; use Script Manager for those.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

#### Form submission [#form-submission]

Unbounce exposes `window.ub.hooks`, an unofficial hook that runs after a lead is recorded. Add this as a second Script Manager script (or page script) with placement **Before Body End Tag** to send a `lead` event with the page name and variant:

```html
<script>
window.ub.hooks.afterFormSubmit.push(function () {
  if (window.rybbit) {
    window.rybbit.event("lead", {
      page: window.ub.page.name,
      variant: window.ub.page.variantId
    });
  }
});
</script>
```

`window.ub.page.name`, `window.ub.page.variantId` and `window.ub.page.id` are available on every Unbounce page, so you can compare A/B variants in Rybbit without any other setup.

## Troubleshooting [#troubleshooting]

* **Script runs twice**: a script that is both in Script Manager and on an individual page loads twice. Remove the page-level copy and keep the Script Manager one.
* **Nothing on `unbouncepages.com`**: Script Manager only applies to custom domains. Add the snippet at page level to test on the Unbounce test domain.
* **Script Manager missing**: the account is on the Starter plan, which does not include custom scripts.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# v0 (/zh/docs/guides/v0)





v0 generates Next.js apps, so there is no single `index.html` and no project setting for head code. The snippet goes into the root layout, `app/layout.tsx`, through a `next/script` tag that renders on every page. Ask v0 to add it or edit the file in the Code tab, then publish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to v0 [#add-the-snippet-to-v0]

    <Tabs items="[&#x22;Ask v0&#x22;, &#x22;Edit app/layout.tsx&#x22;]">
      <Tab>
        Paste this into the chat, with your site ID in place of the placeholder:

        ```text
        Add the Rybbit analytics script to the root layout (app/layout.tsx) using next/script with strategy="afterInteractive", so it loads on every page:
        https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID
        ```

        Check the diff: the `<Script>` belongs in `app/layout.tsx`, not in a page or component.
      </Tab>

      <Tab>
        Select the **Code** tab in the preview toolbar, open `app/layout.tsx` and add the `Script` component inside `<body>`. The `defer` attribute from the snippet is not needed; the strategy handles timing.

        ```tsx title="app/layout.tsx"
        import Script from "next/script";

        export default function RootLayout({ children }: { children: React.ReactNode }) {
          return (
            <html lang="en">
              <body>
                {children}
                <Script
                  src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"
                  strategy="afterInteractive"
                />
              </body>
            </html>
          );
        }
        ```

        Press **Cmd+S** / **Ctrl+S** to save.
      </Tab>
    </Tabs>

    Click **Publish** in the top right of the chat, then **Publish to Production**. Navigation through `<Link>` and `router.push()` is tracked as pageviews automatically.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Call `window.rybbit.event()` from a client component. Guard the call, because v0 components can render on the server and the script loads after hydration.

```tsx title="components/signup-button.tsx"
"use client";

export function SignupButton() {
  const handleClick = () => {
    if (typeof window !== "undefined" && window.rybbit) {
      window.rybbit.event("signup_click", { location: "hero" });
    }
  };

  return <button onClick={handleClick}>Sign up</button>;
}
```

## Troubleshooting [#troubleshooting]

* **Production has no script**: the preview updates on save, but the live site only changes after **Publish to Production**. Projects connected to GitHub go through a pull request that v0 merges before the production deployment runs.
* **v0 rewrote the layout**: a later prompt can regenerate `app/layout.tsx`. Add "keep the Rybbit Script tag in app/layout.tsx" to the project's custom instructions, and re-check the page source after large changes.
* **Pages Router**: if your project has `pages/` instead of `app/`, put the `Script` in `pages/_app.tsx` as shown in the [Next.js guide](/docs/guides/react/next-js).

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# VitePress (/zh/docs/guides/vitepress)





VitePress has a `head` option in `.vitepress/config.ts` that adds tags to every page, which is where the snippet goes. A custom theme is the fallback when you need to load it conditionally at runtime.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to VitePress [#add-the-snippet-to-vitepress]

    <Tabs items="[&#x22;Config file&#x22;, &#x22;Custom theme&#x22;]">
      <Tab>
        Edit `.vitepress/config.ts` (or `.js` / `.mts`) and add the tag to `head`:

        ```typescript filename=".vitepress/config.ts"
        import { defineConfig } from "vitepress";

        export default defineConfig({
          // ... your other config
          head: [
            [
              "script",
              {
                src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",
                defer: "",
              },
            ],
          ],
        });
        ```

        <Callout type="info">
          The empty string for `defer` is intentional. VitePress renders it as a boolean attribute.
        </Callout>

        To track production only, make `head` conditional:

        ```typescript filename=".vitepress/config.ts"
        const isProd = process.env.NODE_ENV === "production";

        export default defineConfig({
          head: isProd
            ? [["script", { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: "" }]]
            : [],
        });
        ```
      </Tab>

      <Tab>
        If you need runtime control, inject the tag from a custom theme. Create or edit `.vitepress/theme/index.ts`:

        ```typescript filename=".vitepress/theme/index.ts"
        import { type Theme } from "vitepress";
        import DefaultTheme from "vitepress/theme";

        export default {
          extends: DefaultTheme,
          enhanceApp() {
            if (typeof window === "undefined") return;

            const el = document.createElement("script");
            el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
            el.defer = true;
            document.head.appendChild(el);
          },
        } satisfies Theme;
        ```

        The `window` check keeps the injector out of the server-side build.
      </Tab>
    </Tabs>

    VitePress navigates between pages client-side. Rybbit picks up those History API changes as pageviews, so no extra code is needed.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Tag missing in `vitepress dev`**: if you used the `isProd` guard, the tag only renders in `vitepress build`. Remove the guard to test locally.
* **Pageviews stop after navigation**: check the browser console for errors thrown by other `head` scripts or theme code; an exception during route change can block Rybbit's listener.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Webflow (/zh/docs/guides/webflow)





Webflow accepts custom `<head>` code either site-wide in **Site settings → Custom code** or per page in the page settings. Either way the code only reaches the live site when you publish.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Webflow [#add-the-snippet-to-webflow]

    <Tabs items="[&#x22;Site-wide&#x22;, &#x22;Single page&#x22;]">
      <Tab value="Site-wide">
        1. Open your project and go to **Site settings → Custom code**.
        2. Paste the snippet into **Head code**.
        3. Click **Save**, then **Publish** the site.
      </Tab>

      <Tab value="Single page">
        Use this when you only want to track specific pages.

        1. In the Designer, open the page's **Settings** (cog icon next to the page name).
        2. Scroll to **Custom code** and paste the snippet into **Inside `<head>` tag**.
        3. Click **Save**, then **Publish** the site.
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

Give the element an **ID** in the Designer (**Settings** panel → **General** → **ID**), then attach a listener in **Site settings → Custom code → Footer code** or in an **Embed** element on that page:

```html
<script>
  document.addEventListener("DOMContentLoaded", function () {
    var button = document.getElementById("my-special-button");
    if (!button) return;
    button.addEventListener("click", function () {
      window.rybbit?.event("button_click", {
        button_id: "my-special-button",
        page_path: window.location.pathname,
      });
    });
  });
</script>
```

The same pattern works for a Form Block's `submit` event. Webflow handles form submission itself, so this fires on the submit attempt, not on confirmed success.

## Troubleshooting [#troubleshooting]

* **Changes not showing on the live site**: custom code is staged until you **Publish**. Check the published site, not the Designer preview.
* **Interactions that show or hide sections** without changing the URL produce a single pageview. Track those states as custom events, or call `window.rybbit.pageview()` from your own script when they appear.
* **Scripts that read the DOM** belong in **Footer code**, not **Head code**, so the elements exist when they run.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Weebly (/zh/docs/guides/weebly)





Weebly (now part of Square) has site-wide **Header Code** and **Footer Code** fields under its SEO settings. Header code is printed into the `<head>` of every page, so the snippet goes there and no theme edits are needed.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Weebly [#add-the-snippet-to-weebly]

    1. Open your site in the Weebly editor and go to **Settings > SEO**.
    2. Paste the snippet into **Header Code** and click **Save**.
    3. Click **Publish**. Header code changes only reach the live site after you publish.

    If your editor has no **Settings** tab, the same header-code option is under **Website > General Settings** in the Square dashboard.

    Site-level header code covers every page, including blog posts. Each page also has its own **Header Code** box in its page settings; that one is for page-specific code and is not needed for the snippet.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet saved but not in the page source**: the site was not republished. Click **Publish** after every change to header code.
* **Snippet appears twice**: it was added both site-wide and on individual pages. Keep only the site-level entry under **Settings > SEO**.
* **Footer Code instead of Header Code**: both fields are included on every page, so the snippet works from either, but the footer loads later and misses visitors who leave early.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Wix (/zh/docs/guides/wix)





Wix adds third-party scripts through the **Custom Code** panel in the site dashboard, where you choose which pages load the code and where in the document it goes.

<Callout type="warn">
  Custom code requires a **Wix Premium plan** and a **connected domain**. It is not available on free Wix sites.
</Callout>

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Wix [#add-the-snippet-to-wix]

    1. Open your site's dashboard and go to **Settings**.
    2. Open **Custom Code** (under **Advanced**). Older dashboards list it as **Tracking Tools & Analytics** under **Marketing & SEO**.
    3. Click **+ Add Custom Code** and paste the snippet into the code box.
    4. Name the code, for example `Rybbit`.
    5. Under **Add Code to Pages**, choose **All pages** and **Load code once**. The script tracks Wix's client-side navigation itself, so loading it on every page change would inject it repeatedly.
    6. Under **Place Code in**, choose **Head**.
    7. Click **Apply**.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Custom Code is missing from Settings**: the site has no Premium plan or no connected domain. Both are required before the panel appears.
* **Duplicate pageviews**: the code was added with **Load code on each new page**. Edit the entry and switch to **Load code once**.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# WooCommerce (/zh/docs/guides/woocommerce)





WooCommerce runs on WordPress, so the snippet goes in the same way as on any WordPress site. What this guide adds is the WooCommerce action hooks that send purchases, add-to-carts, product views and checkouts to Rybbit as custom events.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to WooCommerce [#add-the-snippet-to-woocommerce]

    Follow the [WordPress guide](/docs/guides/wordpress) to add the snippet. If you plan to track the e-commerce events below, use the `functions.php` or mini-plugin method there: the event hooks are PHP and belong in the same file.

    ```php
    function rybbit_add_tracking_script() {
        ?>
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        <?php
    }
    add_action( 'wp_head', 'rybbit_add_tracking_script' );
    ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Track custom events [#track-custom-events]

WooCommerce fires PHP action hooks at each stage of the shopping flow. The snippets below print a small inline script from those hooks. They wait for `DOMContentLoaded` because the tracking script is loaded with `defer`, so `window.rybbit` does not exist while the page is still parsing.

<Callout type="warn">
  Add these to your &#x2A;*child theme's `functions.php`** or a site-specific plugin, never to the parent theme.
</Callout>

#### Purchase [#purchase]

`woocommerce_thankyou` fires on the order-received page with the order ID.

```php
add_action( 'woocommerce_thankyou', 'rybbit_track_purchase', 10, 1 );
function rybbit_track_purchase( $order_id ) {
    $order = wc_get_order( $order_id );
    if ( ! $order ) {
        return;
    }

    $items = array();
    foreach ( $order->get_items() as $item ) {
        $product = $item->get_product();
        $items[] = array(
            'item_id'   => $product && $product->get_sku() ? $product->get_sku() : $item->get_product_id(),
            'item_name' => $item->get_name(),
            'price'     => (float) $order->get_line_subtotal( $item, false, false ),
            'quantity'  => (int) $item->get_quantity(),
        );
    }

    $purchase = array(
        'transaction_id' => $order->get_order_number(),
        'value'          => (float) $order->get_total(),
        'tax'            => (float) $order->get_total_tax(),
        'shipping'       => (float) $order->get_shipping_total(),
        'currency'       => $order->get_currency(),
        'items'          => $items,
    );
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function () {
        window.rybbit.event('purchase', <?php echo wp_json_encode( $purchase ); ?>);
    });
    </script>
    <?php
}
```

Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.

#### Add to cart [#add-to-cart]

Two hooks cover both paths: the product-page form submit, and WooCommerce's `added_to_cart` jQuery event for AJAX buttons on shop and category pages.

```php
// Single product page: track on form submit
add_action( 'woocommerce_after_add_to_cart_button', 'rybbit_track_add_to_cart' );
function rybbit_track_add_to_cart() {
    global $product;
    if ( ! $product instanceof WC_Product ) {
        return;
    }
    $data = array(
        'item_id'   => $product->get_sku() ? $product->get_sku() : $product->get_id(),
        'item_name' => $product->get_name(),
        'price'     => (float) $product->get_price(),
        'currency'  => get_woocommerce_currency(),
    );
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function () {
        var form = document.querySelector('form.cart');
        if (!form) return;
        form.addEventListener('submit', function () {
            var data = <?php echo wp_json_encode( $data ); ?>;
            var qty = form.querySelector('input.qty');
            data.quantity = qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1;
            window.rybbit.event('add_to_cart', data);
        });
    });
    </script>
    <?php
}

// AJAX add-to-cart buttons on shop and category pages
add_action( 'wp_footer', 'rybbit_track_ajax_add_to_cart' );
function rybbit_track_ajax_add_to_cart() {
    if ( is_admin() ) {
        return;
    }
    ?>
    <script>
    jQuery(document.body).on('added_to_cart', function (event, fragments, cartHash, $button) {
        if (!$button || !$button.length) return;
        window.rybbit.event('add_to_cart', {
            item_id: $button.data('product_id'),
            quantity: $button.data('quantity') || 1,
            source: 'ajax_add_to_cart'
        });
    });
    </script>
    <?php
}
```

The AJAX handler only sees the product ID and quantity from the button's `data-*` attributes. Add attributes to the button in your theme if you also want name and price.

#### View product and begin checkout [#view-product-and-begin-checkout]

The same pattern works for the remaining hooks:

* `woocommerce_after_single_product_summary` runs on product pages. Guard with `is_product()`, then send `view_item` with `item_id`, `item_name`, `price` and `currency` from the global `$product`.
* `woocommerce_before_checkout_form` runs on the checkout page. Build `begin_checkout` from `WC()->cart`: loop over `get_cart()` for the items (each `$cart_item['data']` is the product, `$cart_item['quantity']` the quantity), with `value` from `$cart->get_total( 'edit' )` and `currency` from `get_woocommerce_currency()`.

## Troubleshooting [#troubleshooting]

* **Events fire before the tracker loads**: keep the tracking snippet in `wp_head` and the `DOMContentLoaded` wrapper in place. Deferred scripts run before `DOMContentLoaded`, so `window.rybbit` is ready by then; calling it from a bare inline script drops the event.
* **AJAX carts and mini-carts**: themes that update the cart without a page load never hit the PHP hooks, so rely on the `added_to_cart` listener for those and test each add-to-cart path.
* **Other analytics plugins**: plugins that also print e-commerce data layers can conflict. Test with a real order after enabling both.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# WordPress (/zh/docs/guides/wordpress)





WordPress has no built-in header-code setting, so the snippet goes in through a plugin such as **WPCode** or through your theme's `functions.php` or `header.php`. Every method below works on self-hosted WordPress.org sites; on WordPress.com you need the Business plan or higher before you can install plugins or add custom JavaScript.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to WordPress [#add-the-snippet-to-wordpress]

    <Callout type="warn">
      If you edit theme files, edit a **child theme**. Changes to a parent theme's `functions.php` or `header.php` are lost on the next theme update.
    </Callout>

    <Tabs items="[&#x22;WPCode&#x22;, &#x22;functions.php&#x22;, &#x22;header.php&#x22;, &#x22;Mini plugin&#x22;]">
      <Tab>
        WPCode (formerly Insert Headers and Footers) is the recommended method: it survives theme updates, works with page builders, and is available on WordPress.com Business plans.

        1. Go to **Plugins > Add New**, search for "WPCode", then install and activate it.
        2. Go to **Code Snippets > Header & Footer** (**Settings > Insert Headers and Footers** in older versions).
        3. Paste the snippet into the **Header** box and click **Save Changes**.
      </Tab>

      <Tab>
        1. Go to **Appearance > Theme File Editor** and open your child theme's `functions.php`.
        2. Add this to the end of the file, replacing `YOUR_SITE_ID`:

        ```php
        function rybbit_add_tracking_script() {
            ?>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
            <?php
        }
        add_action( 'wp_head', 'rybbit_add_tracking_script' );
        ```

        3. Save the file.
      </Tab>

      <Tab>
        1. Go to **Appearance > Theme File Editor** and open your child theme's `header.php`.
        2. Paste the snippet just before the closing `</head>` tag:

        ```html
        <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
        </head>
        ```

        3. Save the file.
      </Tab>

      <Tab>
        A one-file plugin keeps the snippet in place through theme changes without touching theme files.

        1. Over FTP/SFTP or a file-manager plugin, create the folder `/wp-content/plugins/rybbit-analytics/`.
        2. Inside it, create `rybbit-analytics.php` with this content, replacing `YOUR_SITE_ID`:

        ```php
        <?php
        /**
         * Plugin Name: Rybbit Analytics
         * Description: Adds the Rybbit tracking script to every page
         * Version: 1.0
         */

        function rybbit_add_tracking_script() {
            ?>
            <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
            <?php
        }
        add_action( 'wp_head', 'rybbit_add_tracking_script' );
        ```

        3. Go to **Plugins** and activate **Rybbit Analytics**.
      </Tab>
    </Tabs>

    Running WooCommerce? Once the snippet is in place, see the [WooCommerce guide](/docs/guides/woocommerce) for purchase and add-to-cart events.
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Caching plugins**: after saving the snippet, purge WP Super Cache, W3 Total Cache, LiteSpeed Cache or whichever cache plugin you run, plus any CDN cache such as Cloudflare, before you check the page source.
* **Script optimisers**: "Delay JavaScript execution" features in WP Rocket, Perfmatters and FlyingPress rebuild script tags and drop `data-*` attributes, which is why the snippet passes the site ID in the URL (`?siteId=`). If tracking still fails, exclude `app.rybbit.io` from optimisation: Autoptimize's exclusion list, WP Rocket's JavaScript optimisation and delay-JS exclusions, Perfmatters / FlyingPress delay-JS exclusions, LiteSpeed Cache JS excludes, SG Optimizer combine/minify.
* **Page builders** (Elementor, Divi, WPBakery, Beaver Builder): add the snippet with WPCode rather than a builder's custom HTML block. Builders sanitise HTML and can strip attributes from script tags.
* **Security plugins**: Wordfence, Sucuri and similar plugins can block external scripts. Add `app.rybbit.io` to the allowlist.
* **WordPress.com plans**: Free, Personal and Premium plans cannot add custom JavaScript. Upgrade to Business or eCommerce and use the WPCode method.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Zola (/zh/docs/guides/zola)





Zola pages extend a base Tera template, normally `templates/base.html`, so the snippet goes in that file's `<head>`. Keep the site ID in the `[extra]` section of `config.toml`, which every template can read as `config.extra`.

<Steps>
  <Step>
    ### Get your tracking snippet [#get-your-tracking-snippet]

    In your Rybbit dashboard, open **Site Settings → Tracking Script** and copy your snippet. It looks like this:

    ```html
    <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
    ```

    `YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
  </Step>

  <Step>
    ### Add the snippet to Zola [#add-the-snippet-to-zola]

    1. Add your site ID under `[extra]` in `config.toml`. `rybbit_instance_url` is only needed if you self-host:

       ```toml title="config.toml"
       [extra]
       rybbit_site_id = "YOUR_SITE_ID"
       rybbit_instance_url = "https://app.rybbit.io"
       ```

    2. Open `templates/base.html` and add the tag inside `<head>`. The `config.mode` check keeps the script out of `zola serve`, so local development is not tracked:

       ```html title="templates/base.html"
       <head>
         ...
         {% if config.mode == "build" %}
           <script src="{{ config.extra.rybbit_instance_url }}/api/script.js?siteId={{ config.extra.rybbit_site_id }}" defer></script>
         {% endif %}
       </head>
       ```

       If a theme owns `base.html`, copy it from `themes/<theme>/templates/base.html` into your own `templates/` directory first. A template in your site with the same name overrides the theme's copy, so the theme can be updated without losing the change.

    3. Build and deploy the generated `public/` directory:

       ```bash
       zola build
       ```
  </Step>

  <Step>
    ### Verify installation [#verify-installation]

    Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.

    If nothing shows up:

    * View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.
    * Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.
    * Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.
    * See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

* **Snippet missing from the page source**: `zola serve` sets `config.mode` to `serve`, so the guard removes the tag. Check the output of `zola build` instead.
* **`config.mode` is not defined**: older Zola releases do not expose it. Upgrade, or drop the `if` block and accept local pageviews.
* **Pages without the tag**: templates that do not `{% extends "base.html" %}` (a custom `404.html`, or a section template that builds its own `<head>`) need the tag added separately.

## Next steps [#next-steps]

* [Track custom events](/docs/track-events) such as signups, purchases and button clicks.
* [Identify users](/docs/identify-users) to connect sessions to accounts.
* [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.
* [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.


# Astro Proxy Setup (/zh/docs/proxy-guide/astro)





Astro's middleware feature makes it simple to proxy Rybbit tracking. This guide shows how to set up server-side request proxying in your Astro application.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Astro middleware allows you to intercept and modify requests before they're handled, making it perfect for creating a transparent analytics proxy.

**What you'll achieve:**

* Proxy Rybbit endpoints through your Astro site
* Forward necessary headers for accurate tracking
* Simple configuration in `astro.config.mjs`
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Astro 2.0 or later (with SSR or hybrid rendering enabled)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

<Callout type="warn">
  This guide requires SSR (Server-Side Rendering) or hybrid mode. Static sites cannot proxy requests server-side. For static sites on platforms like Vercel or Netlify, use their platform-specific proxy configurations.
</Callout>

## Implementation [#implementation]

<Steps>
  ### Enable SSR in Astro [#enable-ssr-in-astro]

  Update `astro.config.mjs` to enable SSR:

  ```javascript
  // astro.config.mjs
  import { defineConfig } from 'astro/config';
  import node from '@astrojs/node';

  export default defineConfig({
    output: 'server', // or 'hybrid'
    adapter: node({
      mode: 'standalone',
    }),
  });
  ```

  Install the Node adapter if not already installed:

  ```bash
  npm install @astrojs/node
  ```

  ### Configure Environment Variables [#configure-environment-variables]

  Create or update `.env`:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  ### Create Middleware [#create-middleware]

  Create `src/middleware.ts` (or `.js` for JavaScript):

  ```typescript
  // src/middleware.ts
  import type { MiddlewareHandler } from 'astro';

  const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';

  export const onRequest: MiddlewareHandler = async (context, next) => {
    const { request } = context;
    const url = new URL(request.url);

    // Check if this is an analytics request
    if (url.pathname.startsWith('/analytics/')) {
      return proxyToRybbit(request, url.pathname);
    }

    // Continue with normal request handling
    return next();
  };

  async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
    try {
      // Map paths: /analytics/* → /api/*
      let rybbitPath = pathname.replace('/analytics/', '/api/');

      const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;

      // Get client IP from headers
      const forwardedFor = request.headers.get('x-forwarded-for');
      const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';

      // Forward request
      const proxyHeaders = new Headers(request.headers);
      proxyHeaders.set('X-Real-IP', clientIp);
      proxyHeaders.set('X-Forwarded-For', clientIp);

      const response = await fetch(rybbitUrl, {
        method: request.method,
        headers: proxyHeaders,
        body: request.method !== 'GET' ? await request.text() : undefined,
      });

      // Return proxied response
      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
      });
    } catch (error) {
      console.error('Rybbit proxy error:', error);
      return new Response('Analytics proxy error', { status: 500 });
    }
  }
  ```

  For JavaScript projects:

  ```javascript
  // src/middleware.js
  const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';

  export const onRequest = async (context, next) => {
    const { request } = context;
    const url = new URL(request.url);

    if (url.pathname.startsWith('/analytics/')) {
      return proxyToRybbit(request, url.pathname);
    }

    return next();
  };

  async function proxyToRybbit(request, pathname) {
    try {
      // Map paths: /analytics/* → /api/*
      let rybbitPath = pathname.replace('/analytics/', '/api/');

      const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;
      const forwardedFor = request.headers.get('x-forwarded-for');
      const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';

      const proxyHeaders = new Headers(request.headers);
      proxyHeaders.set('X-Real-IP', clientIp);
      proxyHeaders.set('X-Forwarded-For', clientIp);

      const response = await fetch(rybbitUrl, {
        method: request.method,
        headers: proxyHeaders,
        body: request.method !== 'GET' ? await request.text() : undefined,
      });

      return new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
      });
    } catch (error) {
      console.error('Rybbit proxy error:', error);
      return new Response('Analytics proxy error', { status: 500 });
    }
  }
  ```

  ### Update Your Layout [#update-your-layout]

  Add the tracking script to your layout:

  ```astro
  ---
  // src/layouts/Layout.astro
  const { title } = Astro.props;
  ---

  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width" />
      <title>{title}</title>

      <!-- Rybbit Analytics -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
    </head>
    <body>
      <slot />
    </body>
  </html>
  ```

  ### Start Development Server [#start-development-server]

  ```bash
  npm run dev
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Open your site** in a browser with Developer Tools
  2. **Check Network tab**: Requests should go to `/analytics/*`
  3. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Astro middleware intercepts requests before they're processed:

1. Request to `/analytics/script.js` enters middleware
2. Middleware proxies to `https://app.rybbit.io/api/script.js`
3. Client IP headers are preserved
4. Response is returned to browser

## Advanced Configuration [#advanced-configuration]

### Caching with Astro [#caching-with-astro]

Add caching for scripts:

```typescript
// src/middleware.ts
const cache = new Map<string, { response: Response; timestamp: number }>();
const CACHE_TTL = 3600000; // 1 hour in milliseconds

async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
  // Cache GET requests for scripts
  if (request.method === 'GET' && pathname.endsWith('.js')) {
    const cached = cache.get(pathname);

    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
      return cached.response.clone();
    }
  }

  // ... proxy logic

  // Cache the response
  if (request.method === 'GET' && pathname.endsWith('.js')) {
    cache.set(pathname, {
      response: response.clone(),
      timestamp: Date.now(),
    });
  }

  return response;
}
```

### Conditional Proxying [#conditional-proxying]

Only proxy in production:

```typescript
export const onRequest: MiddlewareHandler = async (context, next) => {
  const { request } = context;
  const url = new URL(request.url);

  // Only proxy in production
  if (import.meta.env.PROD && url.pathname.startsWith('/analytics/')) {
    return proxyToRybbit(request, url.pathname);
  }

  return next();
};
```

### Error Logging [#error-logging]

Add detailed error logging:

```typescript
async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {
  try {
    // ... proxy logic
  } catch (error) {
    const errorDetails = {
      message: error instanceof Error ? error.message : 'Unknown error',
      pathname,
      method: request.method,
      timestamp: new Date().toISOString(),
    };

    console.error('Rybbit proxy error:', errorDetails);

    // Return error response
    return new Response(JSON.stringify({ error: 'Analytics proxy error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}
```

## Troubleshooting [#troubleshooting]

### Middleware not running [#middleware-not-running]

**Problem**: Requests bypass middleware.

**Solution**:

1. Ensure SSR or hybrid mode is enabled in `astro.config.mjs`
2. Verify middleware file is in `src/middleware.ts` (not in subdirectory)
3. Check adapter is installed: `npm install @astrojs/node`

### Static build issues [#static-build-issues]

**Problem**: Build fails or proxy doesn't work in production.

**Solution**:
Middleware requires server-side rendering. Ensure:

```javascript
// astro.config.mjs
export default defineConfig({
  output: 'server', // Required for middleware
  adapter: node({
    mode: 'standalone',
  }),
});
```

### Environment variables not loading [#environment-variables-not-loading]

**Problem**: `RYBBIT_HOST` is undefined.

**Solution**:

1. Check `.env` file is in project root
2. Use `import.meta.env.RYBBIT_HOST` (not `process.env`)
3. For production, set environment variables in your hosting platform

## Deployment [#deployment]

### Vercel [#vercel]

Deploy with Vercel adapter:

```bash
npm install @astrojs/vercel
```

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});
```

### Netlify [#netlify]

Deploy with Netlify adapter:

```bash
npm install @astrojs/netlify
```

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify/functions';

export default defineConfig({
  output: 'server',
  adapter: netlify(),
});
```

### Node.js Server [#nodejs-server]

For self-hosting:

```bash
npm run build
node ./dist/server/entry.mjs
```

## Related Resources [#related-resources]

* [Astro Integration Guide](/docs/guides/astro) - General Astro integration
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Astro Middleware](https://docs.astro.build/en/guides/middleware/) - Official Astro docs


# Caddy Proxy Setup (/zh/docs/proxy-guide/caddy)





Caddy is a powerful web server with automatic HTTPS that makes reverse proxying simple and secure. This guide shows how to configure Caddy to proxy Rybbit tracking through your own domain.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Caddy's `reverse_proxy` directive makes it incredibly easy to proxy requests. Combined with automatic HTTPS via Let's Encrypt, Caddy provides a secure, low-configuration solution for proxying analytics.

**What you'll achieve:**

* Automatic HTTPS with Let's Encrypt
* Simple reverse proxy configuration
* Header forwarding for accurate tracking
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Caddy installed (version 2.0 or later)
* Domain pointing to your server
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID (found in your dashboard)

<Callout type="info">
  Caddy automatically obtains and renews SSL certificates from Let's Encrypt. No manual SSL configuration needed!
</Callout>

## Implementation [#implementation]

<Steps>
  ### Configure Caddyfile [#configure-caddyfile]

  Add or update your Caddyfile with the analytics proxy configuration:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'Simplified with Handle Path']">
    <Tab>
      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          # Your main site configuration
          # ...

          # Rybbit Analytics Proxy
          # Main tracking script
          handle /analytics/script.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up X-Forwarded-Proto {scheme}
              }
              rewrite * /api/script.js
          }

          # Session replay script
          handle /analytics/replay.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/replay.js
          }

          # Web Vitals metrics script
          handle /analytics/metrics.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/metrics.js
          }

          # Event tracking endpoint
          handle /analytics/track {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/track
          }

          # User identification endpoint
          handle /analytics/identify {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/identify
          }

          # Session replay recording
          handle /analytics/session-replay/record/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
                  header_up Content-Type {header.Content-Type}
              }
              rewrite * /api/session-replay/record{path}
          }

          # Site configuration
          handle /analytics/site/tracking-config/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/site/tracking-config{path}
          }
      }
      ```

      <Callout type="info">
        Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
      </Callout>
    </Tab>

    <Tab>
      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          # Main tracking script
          handle /analytics/script.js {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/script.js
          }

          # Event tracking
          handle /analytics/track {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api/track
          }
      }
      ```
    </Tab>

    <Tab>
      Caddy 2.4+ supports a cleaner syntax with `handle_path`:

      ```txt
      # /etc/caddy/Caddyfile

      yourdomain.com {
          handle_path /analytics/* {
              reverse_proxy https://app.rybbit.io {
                  header_up Host app.rybbit.io
                  header_up X-Real-IP {remote_host}
                  header_up X-Forwarded-For {remote_host}
              }
              rewrite * /api{uri}
          }
      }
      ```

      This proxies all `/analytics/*` requests to `https://app.rybbit.io/api/*`.
    </Tab>
  </Tabs>

  ### Validate Caddyfile [#validate-caddyfile]

  Test your configuration for syntax errors:

  ```bash
  caddy validate --config /etc/caddy/Caddyfile
  ```

  You should see:

  ```
  Valid configuration
  ```

  ### Reload Caddy [#reload-caddy]

  Apply the changes by reloading Caddy:

  ```bash
  sudo caddy reload --config /etc/caddy/Caddyfile
  ```

  Or if using systemd:

  ```bash
  sudo systemctl reload caddy
  ```

  <Callout type="info">
    Caddy will automatically obtain an SSL certificate from Let's Encrypt on first request if one doesn't exist.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to load the script from your proxied domain:

  ```html
  <!DOCTYPE html>
  <html>
  <head>
      <!-- ... other head elements -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      <!-- Your content -->
  </body>
  </html>
  ```

  Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.

  ### Verify the Setup [#verify-the-setup]

  Test your configuration:

  1. **Check Caddy is running**:
     ```bash
     sudo systemctl status caddy
     ```

  2. **Test script loading**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see `HTTP/2 200` with `content-type: application/javascript`.

  3. **Open your website** in a browser with Developer Tools and verify:
     * Script loads from `/analytics/script.js`
     * Tracking requests go to `/analytics/track`
     * Data appears in Rybbit dashboard
</Steps>

## How It Works [#how-it-works]

Caddy's `reverse_proxy` directive forwards requests to Rybbit's servers:

1. Browser requests `https://yourdomain.com/analytics/script.js`
2. Caddy matches the handle block
3. Rewrites the path to `/api/script.js`
4. Forwards to `https://app.rybbit.io/api/script.js` with proper headers
5. Returns response to browser

The Rybbit script auto-detects it's being served from your domain and sends all tracking to your domain's endpoints.

## Advanced Configuration [#advanced-configuration]

### Caching with Cache-Control [#caching-with-cache-control]

Add caching headers for better performance:

```txt
yourdomain.com {
    # Scripts - cache for 1 hour
    handle /analytics/script.js {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/script.js
        header Cache-Control "public, max-age=3600"
    }

    # Config - cache for 5 minutes
    handle /analytics/site/tracking-config/* {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/site/tracking-config{path}
        header Cache-Control "public, max-age=300"
    }

    # Tracking - no cache
    handle /analytics/track {
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/track
        header Cache-Control "no-store"
    }
}
```

### Subdomain Proxy [#subdomain-proxy]

Use a dedicated subdomain for analytics:

```txt
# /etc/caddy/Caddyfile

analytics.yourdomain.com {
    reverse_proxy https://app.rybbit.io {
        header_up Host app.rybbit.io
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
    }
    rewrite * /api{uri}
}
```

Then use:

```html
<script src="https://analytics.yourdomain.com/script.js" data-site-id="123"></script>
```

### Request Size Limits [#request-size-limits]

For session replay, increase max body size:

```txt
yourdomain.com {
    # Increase request body limit for session replay
    handle /analytics/session-replay/record/* {
        request_body {
            max_size 10MB
        }
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/session-replay/record{path}
    }
}
```

### Environment-Based Configuration [#environment-based-configuration]

Use Caddy's environment variable support:

```txt
# /etc/caddy/Caddyfile

{$DOMAIN:yourdomain.com} {
    handle_path /analytics/* {
        reverse_proxy {$RYBBIT_HOST:https://app.rybbit.io} {
            header_up Host {upstream_hostport}
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api{uri}
    }
}
```

Then set environment variables:

```bash
export DOMAIN=yourdomain.com
export RYBBIT_HOST=https://app.rybbit.io
caddy run
```

### Rate Limiting [#rate-limiting]

Protect your proxy with rate limiting using the `rate_limit` plugin:

```txt
yourdomain.com {
    handle /analytics/track {
        rate_limit {
            zone analytics {
                key {remote_host}
                events 100
                window 1m
            }
        }
        reverse_proxy https://app.rybbit.io {
            header_up Host app.rybbit.io
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
        rewrite * /api/track
    }
}
```

<Callout type="warn">
  The `rate_limit` directive requires the [caddy-ratelimit plugin](https://github.com/mholt/caddy-ratelimit). Install with: `xcaddy build --with github.com/mholt/caddy-ratelimit`
</Callout>

## Troubleshooting [#troubleshooting]

### Certificate errors [#certificate-errors]

**Problem**: Caddy fails to obtain SSL certificate.

**Solution**:

1. Verify domain points to your server (DNS)
2. Check ports 80 and 443 are open
3. Ensure no other process is using port 443
4. Check Caddy logs: `journalctl -u caddy -f`

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show same location.

**Solution**:
Ensure you're forwarding client IP:

```txt
reverse_proxy https://app.rybbit.io {
    header_up X-Real-IP {remote_host}
    header_up X-Forwarded-For {remote_host}
}
```

### 502 Bad Gateway [#502-bad-gateway]

**Problem**: Caddy returns 502 when accessing analytics endpoints.

**Solution**:

1. Verify Rybbit backend is accessible:
   ```bash
   curl -I https://app.rybbit.io/api/script.js
   ```
2. Check Caddy logs for errors:
   ```bash
   journalctl -u caddy -n 50
   ```

### Path rewriting not working [#path-rewriting-not-working]

**Problem**: Requests go to wrong Rybbit endpoints.

**Solution**:
Use the `rewrite` directive correctly:

```txt
handle /analytics/script.js {
    rewrite * /api/script.js  # Rewrite before reverse_proxy
    reverse_proxy https://app.rybbit.io {
        # ... headers
    }
}
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Framework-agnostic concepts
* [Caddy Documentation](https://caddyserver.com/docs/) - Official Caddy docs
* [Caddy reverse\_proxy](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) - Reverse proxy directive docs


# Cloudflare Workers Proxy Setup (/zh/docs/proxy-guide/cloudflare-workers)





Cloudflare Workers provide a serverless way to proxy Rybbit tracking at the edge, close to your users worldwide. This delivers excellent performance with minimal configuration.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Cloudflare Workers run on Cloudflare's global network, intercepting and proxying requests before they reach your origin server. This makes them perfect for analytics proxying with built-in caching and ultra-low latency.

**What you'll achieve:**

* Edge-based proxying in 300+ cities worldwide
* Automatic caching with Cloudflare's Cache API
* Sub-10ms latency for most requests
* Zero server infrastructure needed

## Prerequisites [#prerequisites]

* Cloudflare account with your domain
* Workers enabled on your account (free tier available)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Create Worker [#create-worker]

  Log in to Cloudflare Dashboard and create a new Worker:

  1. Go to **Workers & Pages** → **Create application** → **Create Worker**
  2. Name it `rybbit-proxy` (or your preferred name)
  3. Click **Deploy** to create the worker

  ### Update Worker Code [#update-worker-code]

  Replace the default code with the proxy implementation:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'With Environment Variables']">
    <Tab>
      ```javascript
      // Cloudflare Worker for Rybbit Analytics Proxy

      const RYBBIT_HOST = 'https://app.rybbit.io';

      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request));
      });

      async function handleRequest(request) {
        const url = new URL(request.url);

        // Only proxy /analytics/* paths
        if (!url.pathname.startsWith('/analytics/')) {
          // Pass through to origin
          return fetch(request);
        }

        try {
          return await proxyToRybbit(request, url);
        } catch (error) {
          console.error('Proxy error:', error);
          return new Response('Analytics proxy error', { status: 500 });
        }
      }

      async function proxyToRybbit(request, url) {
        // Map paths: /analytics/* → /api/*
        let rybbitPath = url.pathname.replace('/analytics/', '/api/');

        // Build Rybbit URL
        const rybbitUrl = new URL(rybbitPath, RYBBIT_HOST);
        rybbitUrl.search = url.search; // Preserve query params

        // Get client IP
        const clientIp = request.headers.get('CF-Connecting-IP') ||
                         request.headers.get('X-Forwarded-For') ||
                         '0.0.0.0';

        // Build request headers
        const proxyHeaders = new Headers(request.headers);
        proxyHeaders.set('X-Real-IP', clientIp);
        proxyHeaders.set('X-Forwarded-For', clientIp);
        proxyHeaders.delete('CF-Connecting-IP'); // Remove Cloudflare internal header

        // Build proxy request
        const proxyRequest = new Request(rybbitUrl, {
          method: request.method,
          headers: proxyHeaders,
          body: request.method !== 'GET' && request.method !== 'HEAD' ? request.body : undefined,
        });

        // Check cache for GET requests
        if (request.method === 'GET') {
          const cache = caches.default;
          let response = await cache.match(proxyRequest);

          if (response) {
            // Return cached response
            return new Response(response.body, {
              status: response.status,
              statusText: response.statusText,
              headers: {
                ...Object.fromEntries(response.headers),
                'X-Cache-Status': 'HIT',
              },
            });
          }
        }

        // Fetch from Rybbit
        const response = await fetch(proxyRequest);

        // Cache scripts for 1 hour
        if (request.method === 'GET' && url.pathname.match(/\.(js)$/)) {
          const cacheResponse = new Response(response.body, response);
          cacheResponse.headers.set('Cache-Control', 'public, max-age=3600');
          cacheResponse.headers.set('X-Cache-Status', 'MISS');

          // Clone and cache
          const cache = caches.default;
          await cache.put(proxyRequest, cacheResponse.clone());

          return cacheResponse;
        }

        // Return non-cacheable response
        return new Response(response.body, {
          status: response.status,
          statusText: response.statusText,
          headers: response.headers,
        });
      }
      ```
    </Tab>

    <Tab>
      ```javascript
      // Minimal Cloudflare Worker for Rybbit

      const RYBBIT_HOST = 'https://app.rybbit.io';

      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request));
      });

      async function handleRequest(request) {
        const url = new URL(request.url);

        // Only proxy /analytics/script.js and /analytics/track
        if (url.pathname === '/analytics/script.js' || url.pathname === '/analytics/track') {
          const rybbitPath = url.pathname.replace('/analytics/', '/api/');
          const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;

          const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

          const proxyHeaders = new Headers(request.headers);
          proxyHeaders.set('X-Real-IP', clientIp);
          proxyHeaders.set('X-Forwarded-For', clientIp);

          return fetch(rybbitUrl, {
            method: request.method,
            headers: proxyHeaders,
            body: request.method === 'POST' ? request.body : undefined,
          });
        }

        // Pass through to origin
        return fetch(request);
      }
      ```
    </Tab>

    <Tab>
      Using Workers secrets for configuration:

      ```javascript
      addEventListener('fetch', event => {
        event.respondWith(handleRequest(event.request, event.env));
      });

      async function handleRequest(request, env) {
        const RYBBIT_HOST = env.RYBBIT_HOST || 'https://app.rybbit.io';
        const url = new URL(request.url);

        if (!url.pathname.startsWith('/analytics/')) {
          return fetch(request);
        }

        // Map paths: /analytics/* → /api/*
        let rybbitPath = url.pathname.replace('/analytics/', '/api/');

        const rybbitUrl = new URL(rybbitPath, RYBBIT_HOST);
        const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

        const proxyHeaders = new Headers(request.headers);
        proxyHeaders.set('X-Real-IP', clientIp);
        proxyHeaders.set('X-Forwarded-For', clientIp);

        return fetch(rybbitUrl.toString(), {
          method: request.method,
          headers: proxyHeaders,
          body: request.method !== 'GET' ? request.body : undefined,
        });
      }
      ```

      Set environment variable in Cloudflare Dashboard:
      **Workers & Pages** → Your Worker → **Settings** → **Variables** → Add `RYBBIT_HOST`
    </Tab>
  </Tabs>

  ### Deploy Worker [#deploy-worker]

  Click **Save and Deploy** to publish your worker.

  ### Configure Worker Route [#configure-worker-route]

  Set up a route to trigger the worker:

  1. Go to **Workers & Pages** → Your Worker → **Triggers**
  2. Click **Add route**
  3. Configure:
     * **Route**: `yourdomain.com/analytics/*`
     * **Zone**: Select your domain
  4. Click **Save**

  <Callout type="info">
    The route pattern `yourdomain.com/analytics/*` ensures the worker only runs for analytics requests, not your entire site.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Add the script to your website:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Visit your site** with Developer Tools open
  2. **Check Network tab**:
     * Script loads from `/analytics/script.js`
     * Check response headers for `CF-Cache-Status` (HIT/MISS)
  3. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Cloudflare Workers intercept requests at the edge:

1. Request to `yourdomain.com/analytics/script.js` hits Cloudflare edge
2. Worker checks cache for GET requests
3. If not cached, proxies to `app.rybbit.io/api/script.js`
4. Response is cached at the edge location
5. Subsequent requests serve from edge cache (ultra-fast)

All tracking data flows through Cloudflare's network while preserving client IP information.

## Performance Benefits [#performance-benefits]

### Global Edge Network [#global-edge-network]

* **300+ locations worldwide**: Workers run in Cloudflare data centers globally
* **Sub-10ms cold start**: Faster than traditional serverless
* **Automatic scaling**: Handles traffic spikes without configuration

### Built-in Caching [#built-in-caching]

* **Cache API**: Leverages Cloudflare's massive edge cache
* **Intelligent caching**: Scripts cached at edge, tracking requests passed through
* **Instant cache purge**: Clear cache via Cloudflare API if needed

### Zero Infrastructure [#zero-infrastructure]

* **No servers to manage**: Fully serverless
* **Pay-per-request**: Free tier includes 100,000 requests/day
* **Automatic HTTPS**: Cloudflare handles SSL

## Advanced Configuration [#advanced-configuration]

### Cache Control [#cache-control]

Customize caching behavior:

```javascript
// Cache scripts for different durations
if (url.pathname === '/analytics/script.js') {
  cacheResponse.headers.set('Cache-Control', 'public, max-age=3600'); // 1 hour
} else if (url.pathname === '/analytics/replay.js') {
  cacheResponse.headers.set('Cache-Control', 'public, max-age=7200'); // 2 hours
}
```

### Rate Limiting [#rate-limiting]

Add basic rate limiting:

```javascript
// Simple in-memory rate limiting (per edge location)
const rateLimitMap = new Map();

async function checkRateLimit(ip) {
  const key = `ratelimit:${ip}`;
  const current = rateLimitMap.get(key) || { count: 0, resetAt: Date.now() + 60000 };

  if (Date.now() > current.resetAt) {
    current.count = 0;
    current.resetAt = Date.now() + 60000;
  }

  current.count++;
  rateLimitMap.set(key, current);

  return current.count > 100; // 100 requests per minute
}
```

### Logging and Analytics [#logging-and-analytics]

Log proxy usage:

```javascript
async function handleRequest(request) {
  const startTime = Date.now();

  try {
    const response = await proxyToRybbit(request, url);
    const duration = Date.now() - startTime;

    // Log to Cloudflare Analytics Engine (if enabled)
    console.log({
      path: url.pathname,
      status: response.status,
      duration,
      cached: response.headers.get('X-Cache-Status') === 'HIT',
    });

    return response;
  } catch (error) {
    console.error('Proxy error:', error);
    return new Response('Error', { status: 500 });
  }
}
```

## Cost Considerations [#cost-considerations]

Cloudflare Workers pricing (as of 2024):

* **Free tier**: 100,000 requests/day
* **Paid plan**: $5/month for 10 million requests + $0.50 per million after

For typical traffic:

* 100,000 sessions/month ≈ 200,000-500,000 requests (well within free tier)
* Even with session replay: Usually under 1 million requests/month

<Callout type="info">
  Most sites stay within the free tier. Bandwidth is unlimited on all Cloudflare plans.
</Callout>

## Troubleshooting [#troubleshooting]

### Worker not triggering [#worker-not-triggering]

**Problem**: Requests bypass worker.

**Solution**:

1. Verify route is configured: `yourdomain.com/analytics/*`
2. Check zone matches your domain
3. Ensure orange-cloud (proxy) is enabled on DNS record

### Cache not working [#cache-not-working]

**Problem**: `X-Cache-Status` always shows MISS.

**Solution**:

1. Verify cache key includes important parts:
   ```javascript
   const cacheKey = new Request(rybbitUrl, request);
   ```
2. Ensure `Cache-Control` headers are set
3. Check method is GET (POST requests aren't cached)

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show Cloudflare IPs.

**Solution**:
Use `CF-Connecting-IP` header:

```javascript
const clientIp = request.headers.get('CF-Connecting-IP');
proxyHeaders.set('X-Real-IP', clientIp);
```

### Deployment errors [#deployment-errors]

**Problem**: Worker fails to deploy.

**Solution**:

1. Check syntax in editor (no console.log in production)
2. Verify all async functions use await
3. Test locally with Wrangler:
   ```bash
   npm install -g wrangler
   wrangler dev
   ```

## Local Development [#local-development]

Use Wrangler for local testing:

```bash
# Install Wrangler
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Create worker
wrangler init rybbit-proxy

# Dev server
wrangler dev

# Deploy
wrangler deploy
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/) - Official docs
* [Workers Cache API](https://developers.cloudflare.com/workers/runtime-apis/cache/) - Caching documentation


# Express.js Proxy Setup (/zh/docs/proxy-guide/express)





Express.js makes it easy to proxy Rybbit tracking using middleware. This guide shows how to set up a reverse proxy using `http-proxy-middleware`.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

The `http-proxy-middleware` package provides a simple way to proxy requests in Express applications, making it perfect for routing analytics requests to Rybbit servers.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your Express app
* Forward necessary headers for accurate tracking
* Optional caching for better performance
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Node.js and Express.js application
* npm or yarn package manager
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Install http-proxy-middleware [#install-http-proxy-middleware]

  Install the proxy middleware package:

  ```bash
  npm install http-proxy-middleware
  ```

  Or with yarn:

  ```bash
  yarn add http-proxy-middleware
  ```

  ### Configure Environment Variables [#configure-environment-variables]

  Create or update your `.env` file:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  <Callout type="info">
    Install `dotenv` if not already: `npm install dotenv`
  </Callout>

  ### Add Proxy Middleware to Express [#add-proxy-middleware-to-express]

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'TypeScript']">
    <Tab>
      Add to your Express server file (e.g., `server.js` or `app.js`):

      ```javascript
      // server.js
      require('dotenv').config();
      const express = require('express');
      const { createProxyMiddleware } = require('http-proxy-middleware');

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      // Rybbit Analytics Proxy
      // Proxy all /analytics/* requests to Rybbit
      app.use('/analytics', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api', // Rewrite /analytics/script.js to /api/script.js
        },
        onProxyReq: (proxyReq, req, res) => {
          // Forward client IP for accurate geolocation
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
        logLevel: 'warn',
      }));

      // Exception for site config endpoint (different path structure)
      app.use('/analytics/site/tracking-config', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics/site': '/api/site', // Rewrite to /api/site/tracking-config
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
      }));

      // Your other routes
      app.get('/', (req, res) => {
        res.send('Hello World');
      });

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>

    <Tab>
      Minimal setup with basic tracking:

      ```javascript
      // server.js
      require('dotenv').config();
      const express = require('express');
      const { createProxyMiddleware } = require('http-proxy-middleware');

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      // Proxy script and track endpoints only
      app.use(['/analytics/script.js', '/analytics/track'], createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api',
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp);
          proxyReq.setHeader('X-Real-IP', clientIp);
        },
      }));

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>

    <Tab>
      For TypeScript projects:

      ```typescript
      // server.ts
      import 'dotenv/config';
      import express, { Request, Response } from 'express';
      import { createProxyMiddleware, Options } from 'http-proxy-middleware';

      const app = express();
      const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';

      const proxyOptions: Options = {
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics': '/api',
        },
        onProxyReq: (proxyReq, req, res) => {
          const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
          proxyReq.setHeader('X-Forwarded-For', clientIp as string);
          proxyReq.setHeader('X-Real-IP', clientIp as string);
        },
        logLevel: 'warn',
      };

      app.use('/analytics', createProxyMiddleware(proxyOptions));

      app.use('/analytics/site/tracking-config', createProxyMiddleware({
        target: RYBBIT_HOST,
        changeOrigin: true,
        pathRewrite: {
          '^/analytics/site': '/api/site',
        },
        onProxyReq: proxyOptions.onProxyReq,
      }));

      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Server running on port ${PORT}`);
      });
      ```
    </Tab>
  </Tabs>

  ### Update Your Tracking Script [#update-your-tracking-script]

  In your HTML or template files:

  ```html
  <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  ### Start Your Server [#start-your-server]

  ```bash
  node server.js
  ```

  Or with nodemon for development:

  ```bash
  npm install -D nodemon
  npx nodemon server.js
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Test script endpoint**:
     ```bash
     curl -I http://localhost:3000/analytics/script.js
     ```

  2. **Open your app** in a browser with Developer Tools

  3. **Check Network tab**: Requests should go to `/analytics/*`

  4. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

The `http-proxy-middleware` intercepts requests matching the specified paths and forwards them to Rybbit:

1. Request to `/analytics/script.js` is intercepted
2. Path is rewritten to `/api/script.js`
3. Request is forwarded to `https://app.rybbit.io/api/script.js`
4. Client IP headers are added for accurate tracking
5. Response is sent back to the browser

## Advanced Configuration [#advanced-configuration]

### Caching Responses [#caching-responses]

Add caching for better performance:

```javascript
const NodeCache = require('node-cache');
const cache = new NodeCache({ stdTTL: 3600 }); // 1 hour default

// Install: npm install node-cache

// Caching middleware for scripts
const cacheMiddleware = (req, res, next) => {
  const key = req.originalUrl;
  const cachedResponse = cache.get(key);

  if (cachedResponse) {
    res.set('X-Cache-Status', 'HIT');
    return res.send(cachedResponse);
  }

  // Store original send
  const originalSend = res.send.bind(res);
  res.send = (body) => {
    cache.set(key, body);
    res.set('X-Cache-Status', 'MISS');
    return originalSend(body);
  };
  next();
};

// Apply caching only to script files
app.use('/analytics/script.js', cacheMiddleware);
app.use('/analytics/script.js', createProxyMiddleware({
  // ... proxy config
}));
```

### Request Size Limits [#request-size-limits]

For session replay uploads, increase body size limit:

```javascript
const express = require('express');
const app = express();

// Increase limit for session replay endpoints
app.use('/analytics/session-replay', express.json({ limit: '10mb' }));
app.use('/analytics/session-replay', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  pathRewrite: {
    '^/analytics': '/api',
  },
}));
```

### Rate Limiting [#rate-limiting]

Protect your proxy with rate limiting:

```javascript
const rateLimit = require('express-rate-limit');

// Install: npm install express-rate-limit

const analyticsLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 100, // Limit each IP to 100 requests per minute
  message: 'Too many requests from this IP',
  standardHeaders: true,
  legacyHeaders: false,
});

// Apply to tracking endpoints
app.use('/analytics/track', analyticsLimiter);
app.use('/analytics/track', createProxyMiddleware({
  // ... proxy config
}));
```

### Error Handling [#error-handling]

Add error handling for proxy failures:

```javascript
app.use('/analytics', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  pathRewrite: {
    '^/analytics': '/api',
  },
  onError: (err, req, res) => {
    console.error('Proxy error:', err);
    res.status(500).json({ error: 'Analytics proxy error' });
  },
  onProxyReq: (proxyReq, req, res) => {
    const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
    proxyReq.setHeader('X-Forwarded-For', clientIp);
    proxyReq.setHeader('X-Real-IP', clientIp);
  },
}));
```

### CORS Configuration [#cors-configuration]

If serving API endpoints to other domains:

```javascript
const cors = require('cors');

// Install: npm install cors

app.use('/analytics', cors({
  origin: ['https://yourdomain.com', 'https://www.yourdomain.com'],
  credentials: true,
}));

app.use('/analytics', createProxyMiddleware({
  // ... proxy config
}));
```

## Troubleshooting [#troubleshooting]

### Requests timing out [#requests-timing-out]

**Problem**: Proxy requests hang or timeout.

**Solution**:
Increase timeout limits:

```javascript
app.use('/analytics', createProxyMiddleware({
  target: RYBBIT_HOST,
  changeOrigin: true,
  timeout: 30000, // 30 seconds
  proxyTimeout: 30000,
  pathRewrite: {
    '^/analytics': '/api',
  },
}));
```

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show server's location.

**Solution**:
Ensure IP forwarding is configured:

```javascript
onProxyReq: (proxyReq, req, res) => {
  const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  proxyReq.setHeader('X-Forwarded-For', clientIp);
  proxyReq.setHeader('X-Real-IP', clientIp);
}
```

### Path rewriting issues [#path-rewriting-issues]

**Problem**: 404 errors on Rybbit endpoints.

**Solution**:
Check path rewriting is correct:

```javascript
pathRewrite: {
  '^/analytics': '/api', // /analytics/script.js → /api/script.js
}
```

Debug by logging:

```javascript
onProxyReq: (proxyReq, req, res) => {
  console.log('Proxying:', req.method, req.path, '→', proxyReq.path);
}
```

## Related Resources [#related-resources]

* [Tracking Script Documentation](/docs/script) - Script configuration
* [Generic Proxy Guide](/docs/proxy-guide/get-started) - Core concepts
* [http-proxy-middleware docs](https://github.com/chimurai/http-proxy-middleware) - Middleware documentation


# Generic Proxy Setup (/zh/docs/proxy-guide/get-started)





This guide covers the core concepts for setting up a Rybbit proxy with any reverse proxy or server framework. If your specific framework has a dedicated guide, we recommend following that instead for optimized instructions.

## Prerequisites [#prerequisites]

Before setting up the proxy, ensure you have:

* **A domain or subdomain** where you'll serve the proxied scripts (e.g., `yourdomain.com` or `analytics.yourdomain.com`)
* **SSL/TLS certificate** for HTTPS (required for modern browsers)
* **Server or platform** with reverse proxy capabilities
* **Your Rybbit instance URL**:
  * Cloud: `https://app.rybbit.io`
  * Self-hosted: Your Rybbit instance URL (e.g., `https://analytics.yourcompany.com`)
* **Your Rybbit site ID** (found in your Rybbit dashboard)

## Understanding the Endpoints [#understanding-the-endpoints]

Rybbit uses several endpoints for tracking. You can choose between a minimal setup or full proxy:

<Tabs items="['Minimal Setup', 'Full Setup (Recommended)']">
  <Tab>
    **Required endpoints for basic tracking:**

    | Endpoint         | Method | Purpose                 | Cache    |
    | ---------------- | ------ | ----------------------- | -------- |
    | `/api/script.js` | GET    | Main tracking script    | 1 hour   |
    | `/api/track`     | POST   | Event tracking endpoint | No cache |

    This minimal setup enables basic pageview and event tracking, but won't support session replay or some advanced features.
  </Tab>

  <Tab>
    **All endpoints for complete functionality:**

    | Endpoint                             | Method | Purpose                         | Cache     |
    | ------------------------------------ | ------ | ------------------------------- | --------- |
    | `/api/script.js`                     | GET    | Main tracking script (minified) | 1 hour    |
    | `/api/replay.js`                     | GET    | Session replay recording script | 1 day     |
    | `/api/metrics.js`                    | GET    | Web Vitals metrics script       | 1 day     |
    | `/api/track`                         | POST   | Event tracking endpoint         | No cache  |
    | `/api/identify`                      | POST   | User identification endpoint    | No cache  |
    | `/api/session-replay/record/:siteId` | POST   | Session replay data upload      | No cache  |
    | `/api/site/tracking-config/:siteId`  | GET    | Site configuration              | 5 minutes |

    This setup supports all Rybbit features including session replay, Web Vitals, and custom events.
  </Tab>
</Tabs>

<Callout type="info">
  The session replay and metrics scripts (`/api/replay.js` and `/api/metrics.js`) are loaded dynamically by the main script when those features are enabled in your site settings. You don't need to include them in your HTML.
</Callout>

## Implementation Steps [#implementation-steps]

<Steps>
  ### Configure Your Proxy Rules [#configure-your-proxy-rules]

  Set up your reverse proxy to forward requests from your chosen path (e.g., `/analytics/*`) to the Rybbit server.

  **Generic proxy configuration pattern:**

  ```
  Your domain path          →  Rybbit backend
  -----------------            ---------------
  /analytics/script.js      →  https://app.rybbit.io/api/script.js
  /analytics/track          →  https://app.rybbit.io/api/track
  /analytics/replay.js      →  https://app.rybbit.io/api/replay.js
  ... and so on
  ```

  **Key requirements:**

  * Preserve the HTTP method (GET or POST)
  * Forward the browser's original request headers — pass through **all** incoming headers except `Host` and hop-by-hop headers (`Connection`, `Content-Length`), rather than hand-picking a few. See [Request Header Forwarding](#request-header-forwarding) for why this matters.
  * Maintain request/response body for POST requests
  * Set appropriate Content-Type headers
  * Forward the visitor IP in `X-Forwarded-For`
  * Enable the **First-Party Proxy** toggle for your site (see below)

  ### Enable First-Party Proxy in Site Settings [#enable-first-party-proxy-in-site-settings]

  In your Rybbit dashboard, open **Site Settings → Privacy & Security** and enable **First-Party Proxy**. This tells Rybbit that requests for this site arrive via your proxy, so the visitor IP in `X-Forwarded-For` is trusted directly instead of being inferred from network topology. Without it, Rybbit may attribute traffic to your proxy server's IP — producing wrong geolocation and merging all visitors into a few users.

  ### Configure Caching (Optional but Recommended) [#configure-caching-optional-but-recommended]

  Implement caching to reduce load on Rybbit servers and improve performance:

  **Recommended cache durations:**

  * **Scripts** (`.js` files): 1 hour (3600 seconds)
    * These change infrequently but may be updated for bug fixes
  * **Site configuration** (`/api/site/tracking-config/*`): 5 minutes (300 seconds)
    * Updated when you change settings in the dashboard
  * **Tracking endpoints** (POST requests): Never cache
    * Each request contains unique event data

  **Example cache headers to set:**

  ```
  Cache-Control: public, max-age=3600  # For scripts
  Cache-Control: public, max-age=300   # For config
  Cache-Control: no-store              # For tracking POSTs
  ```

  ### Update Your Tracking Script [#update-your-tracking-script]

  Change your script tag to load from your proxied domain instead of directly from Rybbit:

  **Before (direct loading):**

  ```html
  <script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  **After (proxied):**

  ```html
  <script src="https://yourdomain.com/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  ```

  <Callout type="info">
    **How Auto-Discovery Works**: The Rybbit script automatically extracts the analytics host from its own `src` attribute by splitting on `/script.js`. This means when it loads from `https://yourdomain.com/analytics/script.js`, it automatically sends all tracking data to `https://yourdomain.com/analytics/*` endpoints.
  </Callout>

  ### Verify the Setup [#verify-the-setup]

  Test your proxy configuration to ensure everything works correctly:

  1. **Open your website** in a browser with Developer Tools open
  2. **Go to the Network tab** and filter by "script" or your proxy path
  3. **Verify the script loads**:
     * You should see a request to `yourdomain.com/analytics/script.js`
     * Status should be `200 OK`
     * Content-Type should be `application/javascript`
  4. **Verify tracking works**:
     * Navigate to another page or trigger an event
     * You should see POST requests to `yourdomain.com/analytics/track`
     * Check the response is successful (200 OK)
  5. **Check your Rybbit dashboard**:
     * Wait 1-2 minutes for data to process
     * Verify your session appears in real-time dashboard

  ### Configure Security Headers (Optional) [#configure-security-headers-optional]

  Add security headers to protect your proxy:

  **Recommended headers:**

  ```
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  Referrer-Policy: strict-origin-when-cross-origin
  ```

  **CORS headers** (should be preserved from Rybbit):

  ```
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, OPTIONS
  Access-Control-Allow-Headers: Content-Type
  ```
</Steps>

## Request Header Forwarding [#request-header-forwarding]

Forward the browser's original headers to the Rybbit backend. The simplest and most robust approach is to pass through **every** incoming request header except `Host` and hop-by-hop headers (`Connection`, `Content-Length` — let your HTTP client recompute those).

Why this matters: Rybbit's bot detection scores requests on headers that every real browser sends. A proxy that forwards only `User-Agent` and the visitor IP produces requests that look exactly like a script — the events return `200 OK` but are classified as bot traffic and never appear in your dashboard.

If you must whitelist headers instead of passing everything through, this is the minimum set:

| Header                                                | Purpose                                            | Required    |
| ----------------------------------------------------- | -------------------------------------------------- | ----------- |
| `User-Agent`                                          | Device and browser detection                       | Yes         |
| `X-Forwarded-For`                                     | Visitor IP for geolocation and user identification | Yes         |
| `Accept-Language`                                     | Language detection, bot filtering                  | Yes         |
| `Accept`                                              | Bot filtering                                      | Yes         |
| `Accept-Encoding`                                     | Bot filtering (must include `gzip`)                | Yes         |
| `Sec-Fetch-Site`, `Sec-Fetch-Mode`, `Sec-Fetch-Dest`  | Bot filtering (sent by all Chromium browsers)      | Yes         |
| `Sec-CH-UA`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Platform` | Browser detection                                  | Recommended |
| `Referer`                                             | Referrer tracking                                  | Recommended |
| `Content-Type`                                        | POST body parsing                                  | Yes (POSTs) |

<Callout type="warn">
  **IP Forwarding**: Rybbit uses IP addresses for geolocation (country/city) and creating anonymous user identifiers (hashed IP + User Agent). If you don't forward the visitor IP in `X-Forwarded-For`, all traffic will appear to come from your proxy server's IP.
</Callout>

### Forwarded IP Headers [#forwarded-ip-headers]

Set `X-Forwarded-For` to the original visitor IP before forwarding the request to Rybbit, and enable the **First-Party Proxy** toggle in your site settings so Rybbit trusts it unconditionally.

<Callout type="warn">
  **Use `X-Forwarded-For`, not `X-Real-IP`.** On Rybbit Cloud, `X-Real-IP` is consumed by our edge network (Cloudflare treats it as an internal header) and never reaches the backend — a proxy that relies on it will silently fall back to the wrong IP. `X-Forwarded-For` passes through intact. Coincidentally, AWS CloudFront also cannot send `X-Real-IP` (it's on the [origin custom-header denylist](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html#add-origin-custom-headers-denylist)). Setting `X-Real-IP` as well does no harm on self-hosted instances, but never make it the only IP header.
</Callout>

**Cloudflare Worker example:**

```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

const proxyHeaders = new Headers(request.headers);
proxyHeaders.set('X-Real-IP', clientIp);
proxyHeaders.set('X-Forwarded-For', clientIp);
```

**CloudFront example:**

* Set `X-Forwarded-For` to the viewer IP from a CloudFront Function/Lambda\@Edge (CloudFront cannot forward `X-Real-IP`)
* Forward `User-Agent`, `Referer`, and `Accept-Language`

```javascript
// CloudFront Function (viewer-request)
function handler(event) {
  event.request.headers["x-forwarded-for"] = { value: event.viewer.ip };
  return event.request;
}
```

## Bandwidth Considerations [#bandwidth-considerations]

Proxying adds bandwidth usage to your infrastructure. Here's what to expect:

**Typical bandwidth per session:**

* Initial script load: \~18 KB (one-time per session)
* Pageview tracking: \~0.5-2 KB per pageview
* Custom events: \~0.5-3 KB per event
* Session replay: 50-500 KB per session (if enabled, varies by session length)
* Web Vitals: \~1-2 KB per page

**Estimated monthly bandwidth** for a site with 100,000 monthly sessions:

* Without session replay: \~5-10 GB/month
* With session replay: \~30-80 GB/month

Most modern hosting plans can handle this easily, but verify your bandwidth limits if you have high traffic or session replay enabled.

## Performance Optimization [#performance-optimization]

### Use a CDN [#use-a-cdn]

If your server has CDN capabilities (like Cloudflare, Fastly, or AWS CloudFront), configure it to cache the static scripts:

* Cache scripts at edge locations worldwide
* Reduce latency for global users
* Offload bandwidth from your origin server

### Enable Compression [#enable-compression]

Ensure your proxy enables gzip or brotli compression:

```
Content-Encoding: gzip
```

This can reduce script size by 60-70%, improving load times and reducing bandwidth.

### Connection Reuse [#connection-reuse]

Configure your proxy to maintain persistent connections to Rybbit's backend to reduce latency on repeated requests.

## Common Proxy Patterns [#common-proxy-patterns]

<Tabs items="['Subdomain Proxy', 'Path-Based Proxy']">
  <Tab>
    Use a dedicated subdomain for analytics:

    ```
    https://analytics.yourdomain.com/script.js  →  https://app.rybbit.io/api/script.js
    https://analytics.yourdomain.com/track      →  https://app.rybbit.io/api/track
    ```

    **Pros:**

    * Clean separation of concerns
    * Easy to manage SSL certificate
    * Can use separate CDN configuration

    **Cons:**

    * Additional DNS lookup (minor performance impact)
    * Need to manage subdomain DNS
  </Tab>

  <Tab>
    Use a path on your main domain:

    ```
    https://yourdomain.com/analytics/script.js  →  https://app.rybbit.io/api/script.js
    https://yourdomain.com/analytics/track      →  https://app.rybbit.io/api/track
    ```

    **Pros:**

    * No additional DNS lookup
    * Single SSL certificate
    * Truly first-party from browser perspective

    **Cons:**

    * Must ensure proxy path doesn't conflict with your app routes
  </Tab>
</Tabs>

## Security Considerations [#security-considerations]

### Rate Limiting [#rate-limiting]

Consider adding rate limiting to prevent abuse:

* Limit POST requests to tracking endpoints (e.g., 100 requests per minute per IP)
* Whitelist your Rybbit backend IP if possible
* Monitor for unusual traffic patterns

### Request Size Limits [#request-size-limits]

Set appropriate request body size limits:

* `/api/track`, `/api/identify`: 1 MB max
* `/api/session-replay/record/*`: 10 MB max (session replay can send large payloads)

### HTTPS Only [#https-only]

Always serve your proxy over HTTPS:

* Modern browsers require HTTPS for many features
* Protects user data in transit
* Required for accurate tracking in secure contexts

## Troubleshooting [#troubleshooting]

If something isn't working, check:

1. **Script loads but no events tracked**: Verify all tracking endpoints (`/api/track`, etc.) are proxied
2. **CORS errors**: Ensure CORS headers are preserved from Rybbit backend
3. **404 errors**: Check that URL paths exactly match expected format
4. **Incorrect geolocation**: Verify `X-Forwarded-For` is set to the visitor IP and the **First-Party Proxy** toggle is enabled in site settings
5. **`/track` returns 200 but nothing appears in the dashboard**: Your proxy is probably forwarding too few headers and events are being classified as bot traffic — forward the full browser header set (see [Request Header Forwarding](#request-header-forwarding))
6. **Session replay not working**: Add `/api/replay.js` and `/api/session-replay/record/:siteId` endpoints

For more detailed troubleshooting, see our [troubleshooting guide](/docs/proxy-guide/troubleshooting).

## Next Steps [#next-steps]

Now that you understand the generic concepts, choose your specific framework or platform for detailed implementation instructions:

* [Next.js](/docs/proxy-guide/next-js)
* [Nginx](/docs/proxy-guide/nginx)
* [Caddy](/docs/proxy-guide/caddy)
* [Vercel](/docs/proxy-guide/vercel)
* [Express.js](/docs/proxy-guide/express)
* [Laravel](/docs/proxy-guide/laravel)
* [Astro](/docs/proxy-guide/astro)
* [Cloudflare Workers](/docs/proxy-guide/cloudflare-workers)


# Proxy Setup Guide (/zh/docs/proxy-guide)





Proxying Rybbit's tracking script through your own domain helps bypass ad blockers and improves tracking accuracy by making all analytics requests appear as first-party traffic.

## What is Proxy Setup? [#what-is-proxy-setup]

When you add Rybbit's tracking script directly to your website using the default installation:

```html
<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
```

The browser loads the script from `app.rybbit.io`, which ad blockers can identify and block as third-party analytics. Even though Rybbit is privacy-focused and doesn't use cookies, some ad blockers use aggressive blocking rules that target any analytics domains.

**Proxying solves this** by serving the tracking script and handling tracking requests through your own domain (e.g., `yourdomain.com/analytics/script.js`), making all tracking appear as first-party traffic.

<Callout type="info">
  Rybbit is fully compliant with GDPR, CCPA, and other privacy regulations. It uses cookieless tracking based on IP + User Agent hashing with optional daily rotating salts. Proxying is about improving data accuracy, not circumventing privacy laws.
</Callout>

## Why Proxy Rybbit? [#why-proxy-rybbit]

### Improve Tracking Accuracy [#improve-tracking-accuracy]

Ad blockers are becoming increasingly aggressive and may block analytics scripts regardless of their privacy practices. By proxying through your own domain:

* **Bypass ad blocker detection**: Requests appear as first-party traffic to your own domain
* **Increase data completeness**: Typical improvement of 10-30% in tracked sessions
* **Maintain accurate metrics**: Get a true picture of your website's performance

### Stay Privacy-Compliant [#stay-privacy-compliant]

Proxying doesn't compromise user privacy:

* No cookies are used (Rybbit remains cookieless)
* User data is still processed according to your privacy policy
* GDPR, CCPA, and other privacy regulations remain fully satisfied
* Users can still opt out through browser settings or Do Not Track

### Better Performance (Optional) [#better-performance-optional]

With proper caching configuration, proxying can also improve performance:

* Serve scripts from your CDN or edge network
* Reduce DNS lookups (one less domain to resolve)
* Cache static scripts closer to your users

## How It Works [#how-it-works]

Here's the flow when you proxy Rybbit:

1. **User visits your website**: Your HTML includes the tracking script from your domain
   ```html
   <script src="https://yourdomain.com/analytics/script.js" data-site-id="123"></script>
   ```

2. **Script loads from your domain**: Your server proxies the request to Rybbit's servers
   * Request: `yourdomain.com/analytics/script.js` → proxied to → `app.rybbit.io/api/script.js`

3. **Script auto-discovers analytics host**: The Rybbit script automatically detects the domain it was loaded from
   ```typescript
   // The script extracts the host from its own src attribute
   const analyticsHost = src.split("/script.js")[0];
   // Result: "https://yourdomain.com/analytics"
   ```

4. **Tracking data sent through your domain**: All analytics events are sent to your domain and proxied to Rybbit
   * Event tracking: `yourdomain.com/analytics/track` → proxied to → `app.rybbit.io/api/track`
   * Session replay: `yourdomain.com/analytics/session-replay/record/{siteId}` → proxied
   * Configuration: `yourdomain.com/analytics/site/tracking-config/{siteId}` → proxied

5. **Data appears in your Rybbit dashboard**: No changes needed in the Rybbit interface

<Callout type="warn">
  **Bandwidth Consideration**: All tracking requests will flow through your server infrastructure, which will increase bandwidth usage. For most sites this is minimal (typically 10-50KB per session), but consider this when evaluating hosting costs.
</Callout>

## Choose Your Framework [#choose-your-framework]

Select the framework or platform that matches your setup:

<Cards>
  <Card icon="<SiNextdotjs />" title="Next.js" href="/docs/proxy-guide/next-js" className="flex items-center gap-2" />

  <Card icon="<SiNginx />" title="Nginx" href="/docs/proxy-guide/nginx" className="flex items-center gap-2" />

  <Card title="Caddy" href="/docs/proxy-guide/caddy" className="flex items-center gap-2" />

  <Card icon="<SiVercel />" title="Vercel" href="/docs/proxy-guide/vercel" className="flex items-center gap-2" />

  <Card icon="<SiExpress />" title="Express.js" href="/docs/proxy-guide/express" className="flex items-center gap-2" />

  <Card icon="<SiLaravel />" title="Laravel" href="/docs/proxy-guide/laravel" className="flex items-center gap-2" />

  <Card icon="<SiAstro />" title="Astro" href="/docs/proxy-guide/astro" className="flex items-center gap-2" />

  <Card icon="<SiCloudflare />" title="Cloudflare Workers" href="/docs/proxy-guide/cloudflare-workers" className="flex items-center gap-2" />
</Cards>

## Generic Implementation [#generic-implementation]

If your framework isn't listed above, check out our [generic implementation guide](/docs/proxy-guide/get-started) that covers the core concepts applicable to any reverse proxy or server setup.

## Need Help? [#need-help]

If you encounter issues during setup, check our [troubleshooting guide](/docs/proxy-guide/troubleshooting) for common problems and solutions.


# Laravel Proxy Setup (/zh/docs/proxy-guide/laravel)





Laravel makes it straightforward to proxy Rybbit tracking using routes and the HTTP client. This guide shows how to set up proxy endpoints in your Laravel application.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Laravel's HTTP client (built on Guzzle) provides an elegant way to proxy requests to Rybbit servers while maintaining full control over headers, caching, and error handling.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your Laravel app
* Forward necessary headers for accurate tracking
* Optional caching with Laravel Cache
* Support all Rybbit features

## Prerequisites [#prerequisites]

* Laravel 8 or later
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID

## Implementation [#implementation]

<Steps>
  ### Configure Environment Variables [#configure-environment-variables]

  Add your Rybbit host to `.env`:

  ```bash
  # .env
  RYBBIT_HOST=https://app.rybbit.io
  # For self-hosted: RYBBIT_HOST=https://analytics.yourcompany.com
  ```

  ### Create Analytics Controller [#create-analytics-controller]

  Generate a controller for handling analytics proxying:

  ```bash
  php artisan make:controller AnalyticsProxyController
  ```

  Then implement the proxy logic:

  ```php
  <?php
  // app/Http/Controllers/AnalyticsProxyController.php

  namespace App\Http\Controllers;

  use Illuminate\Http\Request;
  use Illuminate\Support\Facades\Http;
  use Illuminate\Support\Facades\Cache;

  class AnalyticsProxyController extends Controller
  {
      private string $rybbitHost;

      public function __construct()
      {
          $this->rybbitHost = config('services.rybbit.host', 'https://app.rybbit.io');
      }

      /**
       * Proxy script requests (GET)
       */
      public function proxyScript(Request $request, string $script)
      {
          // Cache scripts for 1 hour
          $cacheKey = "rybbit_script_{$script}";

          return Cache::remember($cacheKey, 3600, function () use ($script, $request) {
              return $this->forwardRequest("api/{$script}", 'GET', $request);
          });
      }

      /**
       * Proxy tracking requests (POST)
       */
      public function proxyTrack(Request $request)
      {
          return $this->forwardRequest('api/track', 'POST', $request);
      }

      /**
       * Proxy identify requests (POST)
       */
      public function proxyIdentify(Request $request)
      {
          return $this->forwardRequest('api/identify', 'POST', $request);
      }

      /**
       * Proxy session replay recording (POST)
       */
      public function proxySessionReplay(Request $request, string $siteId)
      {
          return $this->forwardRequest("api/session-replay/record/{$siteId}", 'POST', $request);
      }

      /**
       * Proxy site configuration (GET)
       */
      public function proxySiteConfig(Request $request, string $siteId)
      {
          // Cache config for 5 minutes
          $cacheKey = "rybbit_config_{$siteId}";

          return Cache::remember($cacheKey, 300, function () use ($siteId, $request) {
              return $this->forwardRequest("api/site/tracking-config/{$siteId}", 'GET', $request);
          });
      }

      /**
       * Forward request to Rybbit backend
       */
      private function forwardRequest(string $path, string $method, Request $request)
      {
          $url = "{$this->rybbitHost}/{$path}";

          // Get client IP
          $clientIp = $request->header('X-Forwarded-For', $request->ip());

          // Build HTTP request
          $httpRequest = Http::timeout(30)
              ->withHeaders([
                  'X-Real-IP' => $clientIp,
                  'X-Forwarded-For' => $clientIp,
                  'User-Agent' => $request->header('User-Agent'),
                  'Referer' => $request->header('Referer', ''),
              ]);

          try {
              if ($method === 'POST') {
                  $response = $httpRequest->post($url, $request->all());
              } else {
                  $response = $httpRequest->get($url);
              }

              return response($response->body(), $response->status())
                  ->header('Content-Type', $response->header('Content-Type'));
          } catch (\Exception $e) {
              \Log::error('Rybbit proxy error', [
                  'url' => $url,
                  'error' => $e->getMessage(),
              ]);

              return response()->json(['error' => 'Analytics proxy error'], 500);
          }
      }
  }
  ```

  ### Add Routes [#add-routes]

  Add routes for the analytics proxy in `routes/web.php`:

  ```php
  <?php
  // routes/web.php

  use App\Http\Controllers\AnalyticsProxyController;

  // Analytics proxy routes
  Route::prefix('analytics')->group(function () {
      // Scripts (GET)
      Route::get('/{script}', [AnalyticsProxyController::class, 'proxyScript'])
          ->where('script', '(script|replay|metrics)\.js');

      // Tracking endpoints (POST)
      Route::post('/track', [AnalyticsProxyController::class, 'proxyTrack']);
      Route::post('/identify', [AnalyticsProxyController::class, 'proxyIdentify']);
      Route::post('/session-replay/record/{siteId}', [AnalyticsProxyController::class, 'proxySessionReplay']);

      // Configuration (GET)
      Route::get('/site/tracking-config/{siteId}', [AnalyticsProxyController::class, 'proxySiteConfig']);
  });
  ```

  ### Add Service Configuration (Optional) [#add-service-configuration-optional]

  Add Rybbit configuration to `config/services.php`:

  ```php
  <?php
  // config/services.php

  return [
      // ... other services

      'rybbit' => [
          'host' => env('RYBBIT_HOST', 'https://app.rybbit.io'),
      ],
  ];
  ```

  ### Update Your Blade Templates [#update-your-blade-templates]

  Add the tracking script to your layout:

  ```blade
  {{-- resources/views/layouts/app.blade.php --}}
  <!DOCTYPE html>
  <html lang="en">
  <head>
      <meta charset="UTF-8">
      <title>{{ config('app.name') }}</title>

      {{-- Rybbit Analytics --}}
      <script src="{{ url('/analytics/script.js') }}" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      @yield('content')
  </body>
  </html>
  ```

  ### Verify the Setup [#verify-the-setup]

  1. **Clear route cache** (if caching enabled):
     ```bash
     php artisan route:clear
     ```

  2. **Visit your application** with Developer Tools open

  3. **Check Network tab**: Requests should go to `/analytics/*`

  4. **Verify in Rybbit dashboard**: Data should appear
</Steps>

## How It Works [#how-it-works]

Laravel routes intercept requests to `/analytics/*` and forward them to Rybbit:

1. Request to `/analytics/script.js` hits Laravel route
2. Controller forwards to `https://app.rybbit.io/api/script.js`
3. Response is cached (for cacheable endpoints)
4. Client IP and headers are preserved for accurate tracking

## Advanced Configuration [#advanced-configuration]

### Middleware for Rate Limiting [#middleware-for-rate-limiting]

Create rate limiting middleware:

```bash
php artisan make:middleware RateLimitAnalytics
```

```php
<?php
// app/Http/Middleware/RateLimitAnalytics.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Cache\RateLimiter;

class RateLimitAnalytics
{
    protected $limiter;

    public function __construct(RateLimiter $limiter)
    {
        $this->limiter = $limiter;
    }

    public function handle($request, Closure $next)
    {
        $key = 'analytics:' . $request->ip();

        if ($this->limiter->tooManyAttempts($key, 100)) {
            return response('Too Many Requests', 429);
        }

        $this->limiter->hit($key, 60); // 100 requests per minute

        return $next($request);
    }
}
```

Register in `app/Http/Kernel.php`:

```php
protected $routeMiddleware = [
    // ... other middleware
    'rate.limit.analytics' => \App\Http\Middleware\RateLimitAnalytics::class,
];
```

Apply to routes:

```php
Route::prefix('analytics')->middleware('rate.limit.analytics')->group(function () {
    // ... routes
});
```

### Custom Cache Configuration [#custom-cache-configuration]

Use different cache drivers for analytics:

```php
private function forwardRequest(string $path, string $method, Request $request)
{
    // Use Redis for analytics caching
    $cache = Cache::store('redis');

    // Or use file cache
    // $cache = Cache::store('file');

    // ... rest of the method
}
```

### Queue Large Requests [#queue-large-requests]

For large session replay uploads, use queues:

```bash
php artisan make:job ForwardAnalyticsData
```

```php
<?php
// app/Jobs/ForwardAnalyticsData.php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Http;

class ForwardAnalyticsData implements ShouldQueue
{
    use Queueable;

    protected $url;
    protected $data;
    protected $headers;

    public function __construct(string $url, array $data, array $headers)
    {
        $this->url = $url;
        $this->data = $data;
        $this->headers = $headers;
    }

    public function handle()
    {
        Http::withHeaders($this->headers)
            ->post($this->url, $this->data);
    }
}
```

Use in controller for session replay:

```php
public function proxySessionReplay(Request $request, string $siteId)
{
    // Dispatch job for async processing
    ForwardAnalyticsData::dispatch(
        "{$this->rybbitHost}/api/session-replay/record/{$siteId}",
        $request->all(),
        [
            'X-Real-IP' => $request->ip(),
            'User-Agent' => $request->header('User-Agent'),
        ]
    );

    return response()->json(['status' => 'queued']);
}
```

### CORS Configuration [#cors-configuration]

If serving from a different domain:

```php
<?php
// config/cors.php

return [
    'paths' => ['analytics/*'],
    'allowed_methods' => ['GET', 'POST'],
    'allowed_origins' => ['https://yourdomain.com'],
    'allowed_headers' => ['Content-Type', 'X-Requested-With'],
];
```

## Troubleshooting [#troubleshooting]

### 404 Not Found [#404-not-found]

**Problem**: Routes return 404.

**Solution**:

1. Clear route cache: `php artisan route:clear`
2. List routes to verify: `php artisan route:list --path=analytics`
3. Check route order (more specific routes first)

### Session errors with POST requests [#session-errors-with-post-requests]

**Problem**: CSRF token errors on tracking endpoints.

**Solution**:
Exclude analytics routes from CSRF protection in `app/Http/Middleware/VerifyCsrfToken.php`:

```php
protected $except = [
    'analytics/*',
];
```

### Incorrect geolocation [#incorrect-geolocation]

**Problem**: All visitors show server's location.

**Solution**:
Ensure IP forwarding in controller:

```php
$clientIp = $request->header('X-Forwarded-For', $request->ip());
```

And add to HTTP request:

```php
'X-Real-IP' => $clientIp,
'X-Forwarded-For' => $clientIp,
```

### Cache not clearing [#cache-not-clearing]

**Problem**: Old script cached after Rybbit update.

**Solution**:
Clear specific cache key:

```bash
php artisan cache:forget rybbit_script_script.js
```

Or clear all cache:

```bash
php artisan cache:clear
```

## Performance Optimization [#performance-optimization]

### Cache Optimization [#cache-optimization]

```php
// Configure cache tags for easy clearing
Cache::tags(['rybbit', 'scripts'])->remember($cacheKey, 3600, function () {
    // ... fetch script
});

// Clear all Rybbit cache
Cache::tags(['rybbit'])->flush();
```

### HTTP Client Optimization [#http-client-optimization]

```php
// Use connection pooling
Http::pool(fn (Pool $pool) => [
    $pool->get("{$this->rybbitHost}/api/script.js"),
    $pool->get("{$this->rybbitHost}/api/replay.js"),
]);
```

## Related Resources [#related-resources]

* [Laravel Integration Guide](/docs/guides/laravel) - General Laravel integration
* [Tracking Script Documentation](/docs/script) - Script configuration
* [Laravel HTTP Client](https://laravel.com/docs/http-client) - Official Laravel docs


# Next.js Proxy Setup (/zh/docs/proxy-guide/next-js)





Next.js provides a powerful [rewrites](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) feature that makes it easy to proxy Rybbit tracking through your own domain. This guide works with both the App Router (Next.js 13+) and Pages Router.

<Callout type="info">
  Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**. Rewrites on this platform automatically forward the browser's headers and set `X-Forwarded-For` to the visitor IP — the toggle tells Rybbit to trust that forwarded IP directly.
</Callout>

## Overview [#overview]

Next.js rewrites allow you to map incoming request paths to different destination URLs transparently. This is perfect for proxying analytics since the browser sees requests to your domain while Next.js forwards them to Rybbit's servers behind the scenes.

**What you'll achieve:**

* Serve Rybbit scripts from your domain (e.g., `/analytics/script.js`)
* Proxy all tracking requests through your Next.js application
* Bypass ad blocker detection with first-party requests
* Support all Rybbit features (session replay, Web Vitals, custom events)

## Prerequisites [#prerequisites]

* Next.js 12 or later (rewrites are supported in all modern versions)
* Your Rybbit site ID (found in your dashboard)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL (e.g., `https://analytics.yourcompany.com`)

## Implementation [#implementation]

<Steps>
  ### Configure Environment Variables [#configure-environment-variables]

  Create or update your `.env` or `.env.local` file with your Rybbit instance URL:

  <Tabs items="['Cloud Hosted', 'Self-Hosted']">
    <Tab>
      ```bash
      # .env.local
      NEXT_PUBLIC_RYBBIT_HOST=https://app.rybbit.io
      ```
    </Tab>

    <Tab>
      ```bash
      # .env.local
      NEXT_PUBLIC_RYBBIT_HOST=https://analytics.yourcompany.com
      ```

      Replace `analytics.yourcompany.com` with your actual Rybbit instance domain.
    </Tab>
  </Tabs>

  <Callout type="info">
    The `NEXT_PUBLIC_` prefix makes this environment variable available in both server and client environments, though it's primarily used during build time for the rewrites configuration.
  </Callout>

  ### Set Up Rewrites in next.config.js [#set-up-rewrites-in-nextconfigjs]

  Add or update the `rewrites` function in your `next.config.js` (or `next.config.mjs` for ESM):

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'ESM (next.config.mjs)']">
    <Tab>
      This configuration proxies all Rybbit endpoints including session replay and Web Vitals:

      ```javascript
      // next.config.js
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            // Tracking scripts
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/replay.js',
              destination: `${rybbitHost}/api/replay.js`,
            },
            {
              source: '/analytics/metrics.js',
              destination: `${rybbitHost}/api/metrics.js`,
            },
            // Tracking endpoints
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
            {
              source: '/analytics/identify',
              destination: `${rybbitHost}/api/identify`,
            },
            {
              source: '/analytics/session-replay/record/:siteId',
              destination: `${rybbitHost}/api/session-replay/record/:siteId`,
            },
            {
              source: '/analytics/site/tracking-config/:siteId',
              destination: `${rybbitHost}/api/site/tracking-config/:siteId`,
            },
          ];
        },
      };

      module.exports = nextConfig;
      ```
    </Tab>

    <Tab>
      Minimal setup with just script loading and basic event tracking:

      ```javascript
      // next.config.js
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
          ];
        },
      };

      module.exports = nextConfig;
      ```

      <Callout type="warn">
        This minimal setup won't support session replay or Web Vitals. Use the full proxy configuration if you need these features.
      </Callout>
    </Tab>

    <Tab>
      If you're using ES modules:

      ```javascript
      // next.config.mjs
      /** @type {import('next').NextConfig} */
      const nextConfig = {
        async rewrites() {
          const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;

          if (!rybbitHost) {
            console.warn('NEXT_PUBLIC_RYBBIT_HOST is not set. Rybbit proxy will not work.');
            return [];
          }

          return [
            {
              source: '/analytics/script.js',
              destination: `${rybbitHost}/api/script.js`,
            },
            {
              source: '/analytics/track',
              destination: `${rybbitHost}/api/track`,
            },
            {
              source: '/analytics/replay.js',
              destination: `${rybbitHost}/api/replay.js`,
            },
            {
              source: '/analytics/metrics.js',
              destination: `${rybbitHost}/api/metrics.js`,
            },
            {
              source: '/analytics/identify',
              destination: `${rybbitHost}/api/identify`,
            },
            {
              source: '/analytics/session-replay/record/:siteId',
              destination: `${rybbitHost}/api/session-replay/record/:siteId`,
            },
            {
              source: '/analytics/site/tracking-config/:siteId',
              destination: `${rybbitHost}/api/site/tracking-config/:siteId`,
            },
          ];
        },
      };

      export default nextConfig;
      ```
    </Tab>
  </Tabs>

  <Callout type="info">
    **Custom Path**: You can change `/analytics` to any path you prefer (e.g., `/tracking`, `/stats`, `/rybbit`). Just ensure you use the same path consistently in both your rewrites and script tag.
  </Callout>

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your script tag to load from the proxied path instead of directly from Rybbit:

  <Tabs items="['App Router (Next.js 13+)', 'Pages Router', 'JavaScript (No TypeScript)']">
    <Tab>
      Update your root layout file:

      ```tsx
      // app/layout.tsx
      import Script from 'next/script';

      export default function RootLayout({
        children,
      }: {
        children: React.ReactNode;
      }) {
        return (
          <html lang="en">
            <body>
              {children}
              <Script
                src="/analytics/script.js"
                data-site-id="YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </body>
          </html>
        );
      }
      ```

      Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.
    </Tab>

    <Tab>
      Update your `_app.tsx` or `_app.jsx` file:

      ```tsx
      // pages/_app.tsx
      import Script from 'next/script';
      import type { AppProps } from 'next/app';

      function MyApp({ Component, pageProps }: AppProps) {
        return (
          <>
            <Component {...pageProps} />
            <Script
              src="/analytics/script.js"
              data-site-id="YOUR_SITE_ID"
              strategy="afterInteractive"
            />
          </>
        );
      }

      export default MyApp;
      ```

      Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.
    </Tab>

    <Tab>
      ```jsx
      // app/layout.js or pages/_app.js
      import Script from 'next/script';

      export default function RootLayout({ children }) {
        return (
          <html lang="en">
            <body>
              {children}
              <Script
                src="/analytics/script.js"
                data-site-id="YOUR_SITE_ID"
                strategy="afterInteractive"
              />
            </body>
          </html>
        );
      }
      ```
    </Tab>
  </Tabs>

  ### Restart Your Development Server [#restart-your-development-server]

  After updating `next.config.js`, restart your Next.js development server for the changes to take effect:

  ```bash
  # Stop the server (Ctrl+C) and restart
  npm run dev
  # or
  yarn dev
  # or
  pnpm dev
  ```

  ### Verify the Setup [#verify-the-setup]

  Open your website in a browser with Developer Tools:

  1. **Open the Network tab** and filter by "analytics" or "script"
  2. **Verify the script loads**:
     * You should see a request to `/analytics/script.js` (not `app.rybbit.io`)
     * Status should be `200 OK`
     * The domain should be your own domain
  3. **Verify tracking works**:
     * Navigate to another page or trigger an event
     * You should see POST requests to `/analytics/track`
     * All requests should show your domain, not `app.rybbit.io`
  4. **Check the Rybbit dashboard**:
     * Wait 1-2 minutes for data processing
     * Verify your session appears in the real-time dashboard
</Steps>

## How It Works [#how-it-works]

The Rybbit tracking script has a built-in auto-discovery mechanism. When it loads from:

```html
<script src="/analytics/script.js" data-site-id="123"></script>
```

It automatically extracts the analytics host from its own `src` attribute:

```typescript
// Inside Rybbit's script
const scriptElement = document.currentScript;
const src = scriptElement.getAttribute('src');
const analyticsHost = src.split('/script.js')[0];
// Result: "" (empty string means same domain)
```

This means all tracking requests automatically go to `/analytics/track`, `/analytics/identify`, etc., which Next.js then rewrites to forward to Rybbit's servers.

## Performance Considerations [#performance-considerations]

### Bandwidth Usage [#bandwidth-usage]

All tracking requests now flow through your Next.js server, which will increase bandwidth usage:

<Callout type="warn">
  **Bandwidth Impact**: Each session typically uses 10-50 KB without session replay, or 50-500 KB with session replay enabled. For a site with 100,000 monthly sessions, expect 5-10 GB/month additional bandwidth without replay, or 30-80 GB/month with replay.
</Callout>

Most Vercel, Netlify, or other hosting plans can handle this, but check your plan's bandwidth limits if you have high traffic.

### Caching [#caching]

Next.js automatically caches responses when possible, but you can optimize further:

**Using Vercel Edge Network:**
If deployed on Vercel, your rewrites benefit from the global Edge Network, which caches static scripts close to users worldwide.

**Custom caching headers:**
The Rybbit server sets cache headers on its scripts, which Next.js respects:

* Scripts (`.js` files): Cached for 1 hour (`script.js`) to 1 day (`replay.js`, `metrics.js`)
* Configuration: Not cached by the server (you may cache it for \~5 minutes at your proxy if desired)
* Tracking POSTs: Not cached

### Server Load [#server-load]

Rewrites are handled at the edge on Vercel, so there's minimal impact on your serverless functions. For self-hosted Next.js, consider:

* Using a CDN (Cloudflare, CloudFront, etc.) in front of Next.js
* Scaling your server if you have very high traffic
* Monitoring server response times

## Troubleshooting [#troubleshooting]

### Script loads but events aren't tracked [#script-loads-but-events-arent-tracked]

**Problem**: You see the script load successfully, but no tracking data appears in the dashboard.

**Solution**:

1. Check that `/analytics/track` is included in your rewrites
2. Verify POST requests to `/analytics/track` return `200 OK` in Network tab
3. Check for CORS errors in the browser console
4. Ensure your Rybbit instance URL is correct in `.env.local`

### 404 errors on tracking endpoints [#404-errors-on-tracking-endpoints]

**Problem**: Script loads fine, but tracking requests return 404.

**Solution**:

1. Verify all tracking endpoints are in your `rewrites()` configuration
2. Restart your dev server after changing `next.config.js`
3. Clear your browser cache
4. Check that the endpoint paths exactly match (case-sensitive)

### Session replay not working [#session-replay-not-working]

**Problem**: Basic tracking works but session replay doesn't record.

**Solution**:
Add the session replay endpoints to your rewrites:

```javascript
{
  source: '/analytics/replay.js',
  destination: `${rybbitHost}/api/replay.js`,
},
{
  source: '/analytics/session-replay/record/:siteId',
  destination: `${rybbitHost}/api/session-replay/record/:siteId`,
},
```

### Environment variable not loading [#environment-variable-not-loading]

**Problem**: Rewrites don't work, console shows warning about missing `NEXT_PUBLIC_RYBBIT_HOST`.

**Solution**:

1. Ensure you created `.env.local` in your project root
2. Restart your dev server after creating `.env.local`
3. For production, ensure environment variables are set in your hosting platform (Vercel, Netlify, etc.)

## Deployment Considerations [#deployment-considerations]

### Vercel [#vercel]

When deploying to Vercel:

1. Add `NEXT_PUBLIC_RYBBIT_HOST` environment variable in your Vercel project settings
2. Rewrites automatically work at the edge with zero configuration
3. Bandwidth is generous on all Vercel plans

### Self-Hosted [#self-hosted]

When self-hosting Next.js:

1. Ensure environment variables are available to the Next.js process
2. Consider adding a CDN layer for better caching and reduced bandwidth
3. Monitor server load if you have high traffic

### Other Platforms (Netlify, AWS, etc.) [#other-platforms-netlify-aws-etc]

1. Set environment variables in your platform's settings
2. Verify rewrites are supported (most platforms support Next.js rewrites)
3. Check bandwidth limits for your plan

## Advanced Configuration [#advanced-configuration]

### Different paths for different environments [#different-paths-for-different-environments]

You can customize the proxy path based on the environment:

```javascript
// next.config.js
const nextConfig = {
  async rewrites() {
    const rybbitHost = process.env.NEXT_PUBLIC_RYBBIT_HOST;
    const analyticsPath = process.env.NODE_ENV === 'development'
      ? '/dev-analytics'
      : '/analytics';

    return [
      {
        source: `${analyticsPath}/script.js`,
        destination: `${rybbitHost}/api/script.js`,
      },
      // ... other rewrites
    ];
  },
};
```

### Conditional proxy (development only) [#conditional-proxy-development-only]

If you only want proxying in production:

```javascript
// next.config.js
const nextConfig = {
  async rewrites() {
    if (process.env.NODE_ENV === 'development') {
      return []; // No proxy in development
    }

    // ... production rewrites
  },
};
```

## Related Resources [#related-resources]

* [Next.js Integration Guide](/docs/guides/react/next-js) - General Next.js integration
* [Tracking Script Documentation](/docs/script) - Script configuration options
* [Custom Events](/docs/track-events) - Track custom events
* [Next.js Rewrites Documentation](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) - Official Next.js docs


# Nginx Proxy Setup (/zh/docs/proxy-guide/nginx)





Nginx is a powerful web server and reverse proxy that makes it easy to proxy Rybbit tracking through your own domain. This guide shows how to configure Nginx to forward tracking requests to Rybbit servers while caching static scripts for better performance.

<Callout type="warn">
  **Two settings make or break a first-party proxy:**

  1. Enable **First-Party Proxy** in your Rybbit **Site Settings → Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
  2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) — proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
</Callout>

## Overview [#overview]

Nginx's `proxy_pass` directive lets you forward requests from your domain to Rybbit's servers. Combined with caching, this provides excellent performance and reliability for proxying analytics.

**What you'll achieve:**

* Proxy all Rybbit endpoints through your domain
* Cache static scripts for better performance
* Forward necessary headers for accurate tracking
* Support all Rybbit features (session replay, Web Vitals, custom events)

## Prerequisites [#prerequisites]

* Nginx installed (version 1.18 or later recommended)
* SSL/TLS certificate configured (Let's Encrypt recommended)
* Your Rybbit instance URL:
  * **Cloud hosted**: `https://app.rybbit.io`
  * **Self-hosted**: Your instance URL
* Your Rybbit site ID (found in your dashboard)

## Implementation [#implementation]

<Steps>
  ### Configure Nginx Proxy [#configure-nginx-proxy]

  Add a new location block (or update existing configuration) in your Nginx site configuration:

  <Tabs items="['Full Proxy (Recommended)', 'Minimal Proxy', 'With Cache Zone']">
    <Tab>
      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          listen 443 ssl http2;
          server_name yourdomain.com;

          # Your SSL configuration
          ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
          ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

          # Your main site configuration
          location / {
              # Your regular site config...
          }

          # Rybbit Analytics Proxy
          # Main tracking script (cached)
          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              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;

              # Cache for 1 hour
              proxy_cache_valid 200 1h;
              proxy_cache_bypass $http_cache_control;
              add_header X-Cache-Status $upstream_cache_status;
          }

          # Session replay script (cached)
          location = /analytics/replay.js {
              proxy_pass https://app.rybbit.io/api/replay.js;
              proxy_set_header Host app.rybbit.io;
              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;

              proxy_cache_valid 200 1h;
          }

          # Web Vitals metrics script (cached)
          location = /analytics/metrics.js {
              proxy_pass https://app.rybbit.io/api/metrics.js;
              proxy_set_header Host app.rybbit.io;
              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;

              proxy_cache_valid 200 1h;
          }

          # Event tracking endpoint (not cached)
          location = /analytics/track {
              proxy_pass https://app.rybbit.io/api/track;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;
          }

          # User identification endpoint (not cached)
          location = /analytics/identify {
              proxy_pass https://app.rybbit.io/api/identify;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;
          }

          # Session replay recording endpoint (not cached)
          location ~ ^/analytics/session-replay/record/(.*)$ {
              proxy_pass https://app.rybbit.io/api/session-replay/record/$1;
              proxy_set_header Host app.rybbit.io;
              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_set_header Content-Type application/json;
              proxy_ssl_server_name on;

              # Allow larger uploads for session replay
              client_max_body_size 10M;
          }

          # Site configuration endpoint (cached briefly)
          location ~ ^/analytics/site/tracking-config/(.*)$ {
              proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
              proxy_set_header Host app.rybbit.io;
              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;

              # Cache for 5 minutes
              proxy_cache_valid 200 5m;
          }
      }
      ```

      <Callout type="info">
        Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.
      </Callout>
    </Tab>

    <Tab>
      Minimal configuration for basic tracking:

      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          listen 443 ssl http2;
          server_name yourdomain.com;

          # SSL configuration
          ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
          ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

          # Main tracking script
          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;

              proxy_cache_valid 200 1h;
          }

          # Event tracking
          location = /analytics/track {
              proxy_pass https://app.rybbit.io/api/track;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;
          }
      }
      ```
    </Tab>

    <Tab>
      For better performance with caching, define a cache zone:

      ```nginx
      # /etc/nginx/nginx.conf (http block)
      http {
          # Define cache zone for Rybbit
          proxy_cache_path /var/cache/nginx/rybbit
              levels=1:2
              keys_zone=rybbit_cache:10m
              max_size=100m
              inactive=60m
              use_temp_path=off;

          # ... rest of http config
      }
      ```

      Then in your site config:

      ```nginx
      # /etc/nginx/sites-available/yourdomain.com
      server {
          # ... server config

          location = /analytics/script.js {
              proxy_pass https://app.rybbit.io/api/script.js;
              proxy_set_header Host app.rybbit.io;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_ssl_server_name on;

              # Use the cache zone
              proxy_cache rybbit_cache;
              proxy_cache_valid 200 1h;
              proxy_cache_key "$scheme$request_method$host$request_uri";
              add_header X-Cache-Status $upstream_cache_status;
          }

          # ... other locations
      }
      ```
    </Tab>
  </Tabs>

  <Callout type="warn">
    **Important**: The `proxy_set_header X-Real-IP` and `X-Forwarded-For` headers are critical for accurate geolocation and user identification. Without these, all traffic will appear to come from your Nginx server's IP.
  </Callout>

  ### Create Cache Directory (Optional) [#create-cache-directory-optional]

  If using a cache zone, create the cache directory:

  ```bash
  sudo mkdir -p /var/cache/nginx/rybbit
  sudo chown www-data:www-data /var/cache/nginx/rybbit
  ```

  ### Test Nginx Configuration [#test-nginx-configuration]

  Before reloading Nginx, test the configuration for syntax errors:

  ```bash
  sudo nginx -t
  ```

  You should see:

  ```
  nginx: configuration file /etc/nginx/nginx.conf test is successful
  ```

  ### Reload Nginx [#reload-nginx]

  Apply the changes by reloading Nginx:

  ```bash
  sudo systemctl reload nginx
  ```

  Or if you prefer:

  ```bash
  sudo nginx -s reload
  ```

  ### Update Your Tracking Script [#update-your-tracking-script]

  Update your HTML to load the script from your proxied domain:

  ```html
  <!DOCTYPE html>
  <html>
  <head>
      <!-- ... other head elements -->
      <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>
  </head>
  <body>
      <!-- Your content -->
  </body>
  </html>
  ```

  Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.

  ### Verify the Setup [#verify-the-setup]

  Test your configuration:

  1. **Check Nginx is running**:
     ```bash
     sudo systemctl status nginx
     ```

  2. **Test script loading**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see:

     ```
     HTTP/2 200
     content-type: application/javascript
     x-cache-status: MISS  # First request
     ```

  3. **Test again to verify caching**:

     ```bash
     curl -I https://yourdomain.com/analytics/script.js
     ```

     You should see:

     ```
     HTTP/2 200
     x-cache-status: HIT  # Cached!
     ```

  4. **Open your website** in a browser with Developer Tools and verify:
     * Script loads from `/analytics/script.js` (your domain)
     * Tracking requests go to `/analytics/track` (your domain)
     * Data appears in your Rybbit dashboard after 1-2 minutes
</Steps>

## How It Works [#how-it-works]

Nginx's `proxy_pass` directive transparently forwards requests to Rybbit's servers:

1. Browser requests `https://yourdomain.com/analytics/script.js`
2. Nginx matches the location block and forwards to `https://app.rybbit.io/api/script.js`
3. Nginx sets necessary headers (`X-Real-IP`, `X-Forwarded-For`) for accurate tracking
4. Response is cached (if configured) and sent back to browser
5. All subsequent tracking requests follow the same pattern

The Rybbit script auto-detects it's being served from your domain and sends all tracking data to your domain's `/analytics/*` endpoints.

## Performance Optimization [#performance-optimization]

### Caching Strategy [#caching-strategy]

Configure different cache durations based on content type:

```nginx
# Scripts - cache for 1 hour
location ~ ^/analytics/(script|replay|metrics)\.js$ {
    proxy_pass https://app.rybbit.io/api/$1.js;
    # ... proxy headers
    proxy_cache_valid 200 1h;
    proxy_cache_valid 404 1m;  # Cache 404s briefly
}

# Config - cache for 5 minutes (changes when you update dashboard settings)
location ~ ^/analytics/site/tracking-config/(.*)$ {
    proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;
    # ... proxy headers
    proxy_cache_valid 200 5m;
}

# Tracking - never cache (each request is unique)
location ~ ^/analytics/(track|identify)$ {
    proxy_pass https://app.rybbit.io/api/$1;
    # ... proxy headers
    # No caching directives
}
```

### Gzip Compression [#gzip-compression]

Enable compression for JavaScript files:

```nginx
# In http or server block
gzip on;
gzip_vary on;
gzip_types application/javascript text/javascript;
gzip_min_length 1000;
```

### Connection Pooling [#connection-pooling]

Keep connections to Rybbit backend alive for better performance:

```nginx
upstream rybbit_backend {
    server app.rybbit.io:443;
    keepalive 32;
}

location /analytics/ {
    proxy_pass https://rybbit_backend/api/;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    #