Rybbit is the modern open source and privacy friendly alternative to Google Analytics. It takes only a couple minutes to setup and is super intuitive to use.
## π Getting Started
There are two ways to start using Rybbit:
| Option | Description |
| -------------------------------------------------------- | ------------------------------------------------------------- |
| **[Hosted Service](https://rybbit.com)** | The fastest way to get started |
| **[Self-Hosting](https://rybbit.com/docs/self-hosting)** | Deploy and manage Rybbit on your own VPS for complete control |
π Explore our [documentation](https://rybbit.com/docs) to learn more about installation, configuration, and usage.
To work on the client and backend locally, see the [pnpm workspace setup](CONTRIBUTE.md#local-development).
## β¨ Key Features
- All key web analytics metrics including sessions, unique users, pageviews, bounce rate, session duration
- Session replays
- No cookies & privacy friendly
- Customizable goals. retention, user journeys, and funnels dashboards
- Advanced filtering across 15+ dimensions
- Custom events with JSON properties
- 3 level location tracking (country -> region -> city) + advanced map visualizations
- Real time dashboard
- Support for organizations and unlimited number of sites
## π Comparison
See how Rybbit compares to other analytics solutions:
| Feature | Rybbit | GA4 | Plausible | Cloudflare |
| --------------------------------- | ------ | ---------- | ---------- | ---------- |
| **Open Source** | β | β | β | β |
| **Self-Hosting** | β | β | β \* | β |
| **Cookieless & Privacy friendly** | β | β | β | β |
| **Advanced Maps** | β | β | β | β |
| **Advanced Filters** | β | β οΈ Limited | β οΈ Limited | β |
| **Web Vitals** | β \*\* | β | β | β |
| **Session Details** | β | β | β | β |
| **User Profiles** | β | β | β | β |
| **Session Replays** | β | β | β | β |
| **Funnels** | β | β | β \*\* | β |
| **User Journeys** | β | β | β | β |
| **Retention Analysis** | β | β | β | β |
| **Goals & Events** | β | β | β | β |
| **Real-time Dashboard** | β | β | β | β |
| **Custom Events (JSON)** | β | β | β οΈ Limited | β |
| **Error Tracking** | β | β | β | β |
| **Public Dashboards** | β | β | β | β |
| **Organizations** | β | β | β | β |
| **Frog πΈ** | β | β | β | β |
\* Plausible's Community Edition has very limited features compared to their cloud version
\*\* Only available on paid tiers
## π Dashboard Preview
### Map
## Session Replay
### Journeys
### Funnels
### Goals
### Users
### Errors
### Retention
### Web Vitals (Cloud only)
## β Star History
[](https://star-history.dera.page/#rybbit-io/rybbit&Date)
---
### README (`docs/README.md`)
# docs-v2
This is a Next.js application generated with
[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
Run development server:
```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```
Open http://localhost:3000 with your browser to see the result.
## Explore
In the project, you can see:
- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
- `app/layout.config.tsx`: Shared options for layouts, optional but preferred to keep.
| Route | Description |
| ------------------------- | ------------------------------------------------------ |
| `app/(home)` | The route group for your landing page and other pages. |
| `app/docs` | The documentation layout and pages. |
| `app/api/search/route.ts` | The Route Handler for search. |
### Fumadocs MDX
A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
## Learn More
To learn more about Next.js and Fumadocs, take a look at the following
resources:
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
- [Fumadocs](https://fumadocs.vercel.app) - learn about Fumadocs
---
### Content Docs (Docs) Index (`docs/content/docs/(docs)/index.mdx`)
---
title: Introduction
description: Introduction to Rybbit
full: true
---
**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.
## 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
Rybbit is open sourced under the AGPL-3.0 license. You can find the code on [GitHub](https://github.com/rybbit-io/rybbit).
## 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.
---
### Content Docs Api Getting Started (`docs/content/docs/api/getting-started.mdx`)
---
title: Getting Started
description: Authentication, common parameters, and best practices for the Rybbit Stats API
---
import { Callout } from 'fumadocs-ui/components/callout';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
The API is currently in beta. There may be breaking changes as we continue to improve and expand the API.
## 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
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
All API requests must include authentication using one of the following methods:
### Bearer Token (Recommended)
```bash
Authorization: Bearer your_api_key_here
```
### Query Parameter (Testing Only)
```bash
?api_key=your_api_key_here
```
Query parameters expose API keys in server logs and browser history. Use only for quick testing.
## 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
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
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)
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
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
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
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
The following parameters are shared across all analytics endpoints.
### Time Parameters
All endpoints require date-based, exact datetime, or relative time parameters:
**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
**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
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
',
typeDescription: 'Multiple values are treated as OR conditions',
required: true,
},
}}
/>
#### Filter Types
#### Available Filter Parameters
**Browser & Device**
**Location**
**Page & Traffic**
**UTM Parameters**
**User & Events**
#### Filter Examples
```json
[
{
"parameter": "country",
"type": "equals",
"value": ["US"]
}
]
```
Multiple filters use AND logic:
```json
[
{
"parameter": "country",
"type": "equals",
"value": ["US", "CA"]
},
{
"parameter": "device_type",
"type": "equals",
"value": ["mobile"]
}
]
```
Substring match:
```json
[
{
"parameter": "pathname",
"type": "contains",
"value": ["/blog"]
}
]
```
Pattern match:
```json
[
{
"parameter": "pathname",
"type": "regex",
"value": ["^/products/[0-9]+$"]
}
]
```
Geolocation comparison:
```json
[
{
"parameter": "lat",
"type": "greater_than",
"value": ["37.0"]
},
{
"parameter": "lat",
"type": "less_than",
"value": ["38.0"]
}
]
```
```
?filters=%5B%7B%22parameter%22%3A%22country%22%2C%22type%22%3A%22equals%22%2C%22value%22%3A%5B%22US%22%5D%7D%5D
```
---
## 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
```json
{
"error": "Error message describing what went wrong"
}
```
---
### Content Partials Guides README (`docs/content/partials/guides/README.md`)
# Integration guide standard
Every page under `content/docs/(docs)/guides/` follows `TEMPLATE.mdx` in this folder.
`npm run lint:guides` checks every guide against the rules below and runs in CI.
## Rules
1. **Frontmatter**: `title` is the platform name as the vendor spells it. `description` is
`Add Rybbit analytics to your site` (use `app`, `store`, `docs`, `blog` when
that is the better noun). `category` is one of the values in `scripts/check-guides.mjs`.
`icon` is an `@icons-pack/react-simple-icons` export name (`SiWordpress`); omit it when
the brand has no icon.
2. **Skeleton**: intro paragraph, then exactly three ``s titled
`Get your tracking snippet`, `Add the snippet to `, `Verify installation`.
Optional `## Track custom events` and `## Troubleshooting`, then `## Next steps`.
3. **Shared content comes from partials**, never retyped:
- `get-snippet.mdx` β the canonical snippet and the self-hosting note.
- `verify.mdx` β the verification checklist.
- `next-steps.mdx` β cross-links.
Include with `../../../partials/guides/.mdx` (one more `../`
from a subfolder such as `react/`). Includes are inlined at build time, so they also
reach the `.mdx` / `llms.txt` endpoints that AI agents read.
4. **Snippet form**: when a guide must show the tag inline (a template file, a config
value, a JS injector), use the URL form `script.js?siteId=YOUR_SITE_ID` with `defer`.
Never the legacy `data-site-id` attribute: script optimisers strip `data-*` attributes.
5. **Only platform-specific content belongs in the guide.** Generic explanations of what
Rybbit is, how events work, GDPR, ad blockers or proxies are linked, not repeated.
6. **Don't invent UI.** Menu paths and file names must be real. If you cannot confirm
where custom head code goes on a platform, say what the setting is usually called and
point to the vendor's own page rather than guessing a path.
7. **Tone**: second person, present tense, imperative steps. No "powerful", "seamless",
"easily". A guide is typically 40β120 lines; length comes from real platform detail,
not padding.
8. **Imports**: double quotes, `Steps` before `Callout` before `Tabs`, only what is used.
9. **Sidebar**: add the slug to `guides/meta.json` under the matching `---Category---`
separator, alphabetically. The index page (`guides/index.mdx`) groups by frontmatter
`category` automatically.
## Adding a guide
```
cp content/partials/guides/TEMPLATE.mdx "content/docs/(docs)/guides/.mdx"
# fill it in, then
npm run lint:guides
```
---
### Content Docs (Docs) Guides Index (`docs/content/docs/(docs)/guides/index.mdx`)
---
title: Integration guides
description: Step-by-step instructions for adding Rybbit to every major website platform, framework and CMS
---
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 `` of every page, or follow the [tracking script](/docs/script) reference.
---
### Content Docs (Docs) Mcp Index (`docs/content/docs/(docs)/mcp/index.mdx`)
---
title: MCP
description: Let an AI assistant explore and manage your Rybbit analytics through the hosted Model Context Protocol server
---
import { Callout } from "fumadocs-ui/components/callout";
import { Cards, Card } from "fumadocs-ui/components/card";
import { SiClaude } from "@icons-pack/react-simple-icons";
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
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. 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
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
```
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 "
}
}
}
}
```
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
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
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
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:
}
title="Claude Code"
description="One command with OAuth or an API key, plus a no-secrets team setup"
href="/docs/mcp/claude-code"
/>
}
title="Claude Desktop"
description="Add a custom connector on claude.ai, desktop, and mobile"
href="/docs/mcp/claude-desktop"
/>
Any other MCP client that supports Streamable HTTP works with the generic configuration from [step 2](#2-add-the-endpoint).
## Available tools
### 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 |
### Search Console (read)
| Tool | Returns |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| `get_search_console_status` | Whether Google Search Console is connected for the site, and which property |
| `get_search_console_data` | Clicks, impressions, CTR, and average position grouped by query, page, country, device, or date |
Search Console tools read the Google Search Console property connected to the site under **Site settings > Integrations** (Rybbit Cloud); no Google Cloud project or separate MCP server is needed. `get_search_console_data` groups by up to three dimensions (`query`, `page`, `country`, `device`, `date`), accepts ANDed filters such as `{"dimension": "page", "operator": "contains", "expression": "/pricing"}`, and returns 100 rows by default (up to 25,000, paged with `start_row`). Google's numbers lag about two days; pass `data_state: "all"` to include fresh, still-changing data. For how this compares with self-run Search Console servers, and prompts that work well, see the [Google Search Console MCP guide](/blog/google-search-console-mcp).
### 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 *(admin)* |
| `update_site_config` | Change site settings: name, domain, tracking features, exclusions, tags *(editor)* |
| `delete_site` | Permanently delete a site and its data *(admin, destructive)* |
### 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 *(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 *(destructive)* |
### 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 *(editor, destructive)* |
### Organization & teams
| Tool | Does |
| --------------------------- | ------------------------------------------------------------------ |
| `list_members` | Organization members with roles, site access, and teams |
| `add_member` | Add an existing Rybbit user to the organization *(admin)* |
| `update_member_site_access` | Restrict a member to specific sites *(admin)* |
| `list_teams` | Teams with members and site access |
| `create_team` | Create a team *(admin)* |
| `update_team` | Rename a team or replace its members/sites *(admin)* |
| `delete_team` | Permanently delete a team *(admin, destructive)* |
### 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
The MCP surface mirrors the REST API's permission model:
- **Read tools** work for any role with access to the site, including viewers.
- **Write tools** need the member role or above on the site (goals, funnels, `identify_user`, `update_user_traits`, `save_funnel`).
- **Tools marked *(editor)*** need the editor role or above on the site.
- **Tools marked *(admin)*** require the API key's user to hold the **admin or owner** role in the organization. `add_member` can't grant a role above the key's own, so only an owner's key can grant `owner`.
A key acts with its user's role on each site, including [site-specific roles](/docs/organization-settings#member-roles) from site restrictions and teams, and it reaches exactly the sites that user can see. The REST layer enforces all of this: an underprivileged key gets a 403 `"Insufficient role"` naming the role required.
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, connect with a viewer's key: it hides nothing but refuses every write.
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
`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
- 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
- **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 holds too low a role for the tool (`"Insufficient role"` names the role required). 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.
- **404 "GSC not connected" from Search Console tools:** Connect Google Search Console for that site under Site settings > Integrations, then retry.
- **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.
---
### Content Docs (Docs) Proxy Guide Index (`docs/content/docs/(docs)/proxy-guide/index.mdx`)
---
title: Proxy Setup Guide
description: Bypass ad blockers and improve tracking accuracy by proxying Rybbit through your own domain
---
import { Cards, Card } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import {
SiAstro,
SiCloudflare,
SiExpress,
SiLaravel,
SiNextdotjs,
SiNginx,
SiVercel
} from '@icons-pack/react-simple-icons';
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?
When you add Rybbit's tracking script directly to your website using the default installation:
```html
```
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.
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.
## Why Proxy Rybbit?
### 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
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)
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
Here's the flow when you proxy Rybbit:
1. **User visits your website**: Your HTML includes the tracking script from your domain
```html
```
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
**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.
## Choose Your Framework
Select the framework or platform that matches your setup:
}
title="Next.js"
href="/docs/proxy-guide/next-js"
className="flex items-center gap-2"
/>
}
title="Nginx"
href="/docs/proxy-guide/nginx"
className="flex items-center gap-2"
/>
}
title="Vercel"
href="/docs/proxy-guide/vercel"
className="flex items-center gap-2"
/>
}
title="Express.js"
href="/docs/proxy-guide/express"
className="flex items-center gap-2"
/>
}
title="Laravel"
href="/docs/proxy-guide/laravel"
className="flex items-center gap-2"
/>
}
title="Astro"
href="/docs/proxy-guide/astro"
className="flex items-center gap-2"
/>
}
title="Cloudflare Workers"
href="/docs/proxy-guide/cloudflare-workers"
className="flex items-center gap-2"
/>
## 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?
If you encounter issues during setup, check our [troubleshooting guide](/docs/proxy-guide/troubleshooting) for common problems and solutions.
---
### Content Docs Api Bots Overview (`docs/content/docs/api/bots/overview.mdx`)
---
title: Get Bot Overview
description: Returns aggregate bot-traffic metrics with a breakdown by detection layer.
full: true
method: GET
---
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
```
GET /api/sites/:site/bots/overview
```
Returns aggregate bot-traffic metrics with a breakdown by detection layer.
### Path 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`.
### Response
---
### Content Docs Api Performance Overview (`docs/content/docs/api/performance/overview.mdx`)
---
title: Get Performance Overview
description: Returns aggregate performance metrics with percentile breakdowns for all Core Web Vitals.
full: true
method: GET
---
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
```
GET /api/sites/:site/performance/overview
```
Returns aggregate performance metrics with percentile breakdowns for all Core Web Vitals.
### Path Parameters
### Query Parameters
Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (time and filters).
### Response
#### PerformanceMetrics Object
Each metric (lcp, cls, inp, fcp, ttfb) includes the following percentiles:
---
### CLAUDE (`docs/CLAUDE.md`)
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Commands
- Dev: `npm run dev` (Next.js with Turbopack on port 3003)
- Build: `npm run build`
- Production: `npm start`
- Type Check: `tsc --noEmit`
- Lint integration guides: `npm run lint:guides` (rules in `content/partials/guides/README.md`; copy `TEMPLATE.mdx` for a new guide)
## Project Overview
This is the documentation and marketing website for Rybbit, built with Next.js 16 and Fumadocs. The site includes:
- Documentation pages (using Fumadocs MDX)
- Blog (separate content collection)
- Marketing pages (home, pricing, features, comparison pages)
- Analytics tools (SEO, ROI calculators, privacy policy builder, etc.)
- LLM-friendly documentation endpoints
- The domain is rybbit.com
## Code Architecture
### Content Management
- **Fumadocs MDX**: Documentation system using `fumadocs-mdx` for MDX processing
- **Source Configuration**: `source.config.ts` defines two content collections:
- `docs`: Documentation pages in `content/docs/`
- `blog`: Blog posts in `content/blog/` with extended frontmatter (date, author, image, tags)
- **Source Adapters**:
- `src/lib/source.ts`: Docs source loader (base URL: `/docs`)
- `src/lib/blog-source.ts`: Blog source loader (base URL: `/blog`)
- **Auto-generated**: `.source/` directory contains generated TypeScript from MDX files
### Route Structure
- `app/(home)/*`: Marketing pages (landing, pricing, features, comparison pages, tools)
- `app/docs/[[...slug]]/`: Documentation pages using catch-all routing
- `app/blog/`: Blog listing and individual posts
- `app/api/search/`: Documentation search powered by Orama
- `app/api/tools/`: API endpoints for tool functionality (SEO generators, analytics detector, etc.)
- `app/llms.mdx/` and `app/llms-full.txt/`: LLM-optimized documentation endpoints
### Internationalization (i18n)
- **Library**: `next-intl` v4 with experimental extract mode enabled
- **Supported Locales**: `en` (default), `de`, `fr`, `zh`, `es`, `pl`, `it`, `ko`, `pt`, `ja`
- **Message Files**: `messages/{locale}.json` β one JSON file per locale with ~242 keys
- **Config Files** in `src/i18n/`:
- `routing.ts`: Locale list and prefix strategy (`as-needed` β no prefix for default `en`)
- `request.ts`: Server-side locale resolution with fallback to `en`
- `navigation.ts`: Locale-aware `Link`, `redirect`, `usePathname`, `useRouter` exports
- **Middleware**: `src/proxy.ts` uses `next-intl/middleware` for automatic locale detection from URL or `Accept-Language` header
- **URL Structure**: Default locale has no prefix (`/pricing`); others are prefixed (`/fr/pricing`)
- **Fumadocs i18n**: `src/lib/i18n.ts` configures the Fumadocs doc tree with the same locales
- **Usage in components**: `const t = useExtracted()` from `next-intl`, then `t("key")` or `t("Welcome {name}", { name })`
- **Language Switcher**: `src/components/LanguageSwitcher.tsx` β client component dropdown for all 10 locales
- **Adding translations**: Add keys to `messages/en.json`, then run `npm run extract` to sync all locale files
- **Automated translation**: `.github/workflows/translate-docs.yml` detects untranslated strings on push to master and opens a PR with AI-generated translations
### Path Aliases
- `@/*`: Maps to `src/*`
- `@/.source`: Maps to `.source/index.ts` (generated MDX content)
## Code Conventions
- Fumadocs for documentation infrastructure; MDX components defined in `src/mdx-components.tsx`
- Tailwind CSS v4 with dark mode support
## Important Notes
- Content files in `content/docs/` and `content/blog/` are processed by Fumadocs MDX
- The `.source/` directory is auto-generated and should not be edited manually
- Next.js rewrites map `/docs/:path*.mdx` to `/llms.mdx/:path*` for LLM consumption
- Remote images allowed from: pbs.twimg.com, abs.twimg.com, ui-avatars.com, cdn.outrank.so, www.google.com
---
### .Design Sync Docs ActivitySlider (`.design-sync/docs/ActivitySlider.md`)
---
category: Replay
---
The session-replay scrubber: a Radix slider whose track shows where the visitor was active and whose rail above it plots the meaningful events (clicks, navigations, typing, rage clicks, console errors) as colored 8px dots, so you can jump straight to the interesting moment. It is the "activity" view of the replay player; `TimelineSlider` is the plain thin transport rail used when there is no event data.
Single part: `ActivitySlider`. It extends every Radix `Slider.Root` prop (`value`/`defaultValue` as `[ms]`, `max`, `step`, `onValueChange`, `disabled`) plus three of its own:
- `duration` (ms, the recording length; ALSO pass it as `max` so the thumb and the rail agree),
- `activityPeriods` (`{ start, end }[]` in ms; drawn as neutral-600 segments on the neutral-700 idle track),
- `events` (raw rrweb events `{ timestamp, type, data }`; the slider runs them through `getMeaningfulEvents` from the replay module, so feed it what the player already has: type 4 Meta for session start/navigation, type 3 source 2 for clicks, source 5 for input, type 6 console plugin for logs).
Marker hues: navigation/console log blue-400, click/double click violet-500, right click fuchsia-500, rage click red-500, typing amber-500, resize cyan-500, console warning yellow-500, console error red-500. Each dot has a 2px ring in the panel color (`ring-neutral-900` in dark) so overlapping dots stay distinct, and its `title` shows the label and offset on hover (not capturable statically). Over 160 markers the plain clicks/typing are sampled while every navigation, rage click and console event is kept. The played portion of the track is emerald (`accent-500`); the thumb is a 16px white disc with an emerald border.
Conventions: mount it inside the player card (neutral-900) with the session identity on the left and `m:ss / m:ss` on the right in 12px muted tabular figures; drive `value` from the player's current time.
```tsx
import { ActivitySlider } from "@rybbit/ui";
player.seek(t)}
activityPeriods={[{ start: 0, end: 30_000 }, { start: 34_000, end: 78_000 }]}
events={rrwebEvents}
/>
```
---
### .Design Sync Docs Alert (`.design-sync/docs/Alert.md`)
---
category: Feedback
---
Inline, non-dismissing status message that lives in the page flow (a settings panel, the top of a report, an onboarding step). Use it for state the user needs to see when they arrive: tracking detected, a plan limit approaching, a failed verification. For a transient confirmation after an action use `Toaster`/`toast`; for something that must be acknowledged use `AlertDialog`.
Parts: `Alert` (root, `role="alert"`, full width, 4.8px radius, 16px/12px padding, tinted fill) β a lucide icon as the first child (absolutely positioned top-left, 16px, tinted to the variant; the text shifts right 28px automatically) β `AlertTitle` (14px medium, one line) β `AlertDescription` (14px, wraps; nested `
` get relaxed leading, so an action row can follow the text).
Variants (`variant` on `Alert`): `default` (neutral-800 fill, gray icon) Β· `info` (blue tint) Β· `success` (emerald tint) Β· `warning` (yellow tint) Β· `destructive` (red tint). There is no border; the hue is carried by the 12-15% tint and the icon only, so the alert sits flat on the panel like everything else in the instrument. Title in sentence case, description says the consequence or the next step; title-only and description-only are both fine for one-liners. Give the icon `className="h-4 w-4"`.
```tsx
import { Alert, AlertDescription, AlertTitle } from "@rybbit/ui";
import { AlertTriangle } from "lucide-react";
Approaching your event limitYou have used 91% of 1M monthly events. Upgrade to keep collecting after the cap.
```
---
### .Design Sync Docs AlertDialog (`.design-sync/docs/AlertDialog.md`)
---
category: Overlays
---
Focus-trapped confirmation prompt (Radix AlertDialog). Unlike `Dialog`, it has no close X, cannot be dismissed by clicking the overlay, and always ends in a choice. Use it before an irreversible or costly action (delete a site, leave an organization, regenerate a key); use `Dialog` for forms and everything else.
Parts: `AlertDialog` (root, `open`/`onOpenChange`) β `AlertDialogTrigger` (`asChild` around a Button) β `AlertDialogContent` (centered 512px panel) β `AlertDialogHeader` / `AlertDialogTitle` / `AlertDialogDescription` β optional body β `AlertDialogFooter` with `AlertDialogCancel` (already styled as an `outline` Button, closes on click) and `AlertDialogAction` (accepts Button `variant` and `size`; closes on click, so attach the real work to `onClick`).
Conventions: title is a question naming the object ("Delete tomato.gg?"); description states the consequence and whether it can be undone; the cancel label is a verb ("Keep site"), not "No". The action is `variant="destructive"` for deletes and `variant="accent"` for non-destructive confirms. Never put more than two buttons in the footer.
```tsx
Delete tomato.gg?
This removes the site and its 2.4M events. This cannot be undone.
Keep siteDelete site
```
---
### .Design Sync Docs Badge (`.design-sync/docs/Badge.md`)
---
category: Data display
---
Small inline status label: 12px medium text, 2px/6px padding, 2.8px radius (`rounded-md`), inline-flex. One export, `Badge`, with a `variant` prop; it renders a `div`, so it is not clickable β wrap it or use a `Button size="xs"` when it must act.
Variants:
- `default` β neutral-800 fill, neutral-100 text. Plan names, generic labels ("Pro").
- `secondary` β one notch quieter (panel fill, neutral-300 text). Counts and low-emphasis tags.
- `success` β emerald 20% tint, emerald-400 text. "Tracking", "Enabled", "Verified".
- `warning` β yellow tint. "No data", "Paused", thresholds.
- `destructive` β red tint. "Bot", "Blocked", "Failed".
- `info` β blue tint. "Beta", "New", informational only (never for data-series color).
- `outline` β neutral-700 border, transparent fill. Environment / category tags.
- `ghost` β no border or fill. Inline keywords.
Conventions: colored variants are semantic, so use them only when the state has that meaning β a status column is the canonical place. Put a 12px lucide icon (`className="h-3 w-3"`) as the first child and add `gap-1`; add `tabular-nums` for counts and `font-mono` for paths. Badges do not change size; if you need a larger pill, it is a `Button`.
```tsx
TrackingNo data Bot2,140
```
---
### .Design Sync Docs BasicTabs (`.design-sync/docs/BasicTabs.md`)
---
category: Navigation
---
Underline tabs (Radix), the quiet sibling of `Tabs`. There is no filled strip: triggers are muted text sitting on a transparent 32px row, and the active one turns bright with a 2px bottom border. Use it inside cards and section headers to switch a breakdown (Countries / Regions / Cities, Channels / Referrers) where a pill strip would be too heavy; use `Tabs` for top-level view switching.
Parts (exported with the `BasicTabs` prefix because the source file shares names with `tabs.tsx`): `BasicTabs` (root; `defaultValue` or `value` / `onValueChange`) β `BasicTabsList` (`inline-flex` row with 12px gaps) β `BasicTabsTrigger` (`value`, `disabled`) and `BasicTabsContent` (`value`; adds `mt-2`).
Conventions: short one-word labels; an optional count after the label as `48`; keep the list flush-left with the card's content edge. Never mix `BasicTabs` and `Tabs` parts in one tree.
```tsx
CountriesRegionsCities{/* ranked list */}β¦β¦
```
---
### .Design Sync Docs Breadcrumb (`.design-sync/docs/Breadcrumb.md`)
---
category: Navigation
---
Location trail for deep pages (a user profile, a funnel, an org settings sub-page). Ancestors are muted links, the current page is bright plain text, and a small chevron separates them. Use it only when the page is two or more levels below a sidebar destination; top-level report pages do not need one.
Parts: `Breadcrumb` (`
