Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

Remove Stats API guide and metric documentation files; update overview documentation to include new structure and references. This streamlines the API documentation and enhances clarity for users.

Bill Yang5588623affe1
diff --git a/docs/content/docs/api/stats/meta.json b/docs/content/docs/api/stats/meta.json
index c338ee7c1..ea383fa51 100644
--- a/docs/content/docs/api/stats/meta.json
+++ b/docs/content/docs/api/stats/meta.json
@@ -1,4 +1,4 @@
{
"title": "Stats",
- "pages": ["guide", "overview", "metric"]
+ "pages": ["reference", "overview"]
}
diff --git a/docs/content/docs/api/stats/metric.mdx b/docs/content/docs/api/stats/metric.mdx
deleted file mode 100644
index 7c9848e85..000000000
--- a/docs/content/docs/api/stats/metric.mdx
+++ /dev/null
@@ -1,157 +0,0 @@
----
-title: Get Metric
-description: Retrieve dimensional analytics data broken down by a specific parameter
----
-
-import { TypeTable } from 'fumadocs-ui/components/type-table';
-
-```
-GET /api/metric/:site
-```
-
-Returns dimensional analytics data broken down by a specific parameter. Supports pagination.
-
-## Path Parameters
-
-<TypeTable
- type={{
- site: {
- description: 'Site ID or site identifier',
- type: 'string | number',
- required: true,
- },
- }}
-/>
-
-## Query Parameters
-
-Accepts all [Common Parameters](/docs/api/stats/guide#common-parameters) plus the following:
-
-<TypeTable
- type={{
- parameter: {
- description: 'The dimension to break down by',
- type: 'FilterParameter',
- typeDescription: 'e.g., "pathname", "country", "browser", "event_name"',
- required: true,
- },
- limit: {
- description: 'Number of results per page',
- type: 'number',
- default: 100,
- },
- page: {
- description: 'Page number (1-indexed)',
- type: 'number',
- default: 1,
- },
- }}
-/>
-
-## 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
-
-<TypeTable
- type={{
- value: {
- description: 'The dimension value',
- type: 'string',
- typeDescription: 'e.g., "/blog", "Chrome", "US"',
- },
- count: {
- description: 'Number of sessions for this value',
- 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: 'Percentage of total pageviews',
- type: 'number',
- required: false,
- },
- time_on_page_seconds: {
- description: 'Average time on page (for page-related parameters)',
- type: 'number',
- required: false,
- },
- bounce_rate: {
- description: 'Bounce rate percentage',
- type: 'number',
- typeDescription: 'Range: 0-100',
- required: false,
- },
- pathname: {
- description: 'Representative pathname (for page_title parameter)',
- type: 'string',
- required: false,
- },
- }}
-/>
-
-## Example Request
-
-```bash
-curl -X GET "https://api.rybbit.com/api/metric/123?parameter=country&start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York&limit=10&page=1" \
- -H "Authorization: Bearer your_api_key_here"
-```
-
-## Example Response
-
-```json
-{
- "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
- }
-}
-```
-
-## Pagination Example
-
-```bash
-# Page 1
-GET /api/metric/123?parameter=pathname&limit=50&page=1
-
-# Page 2
-GET /api/metric/123?parameter=pathname&limit=50&page=2
-```
diff --git a/docs/content/docs/api/stats/overview.mdx b/docs/content/docs/api/stats/overview.mdx
index eb011acf9..750791f88 100644
--- a/docs/content/docs/api/stats/overview.mdx
+++ b/docs/content/docs/api/stats/overview.mdx
@@ -1,9 +1,41 @@
---
-title: Get Overview
+title: Overview
description: Retrieve high-level analytics metrics for a site
+full: true
---
import { TypeTable } from 'fumadocs-ui/components/type-table';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+See the [API Reference](/docs/api/stats/reference) for authentication, common parameters, and filters.
+
+## Endpoints
+
+<div className="flex flex-col gap-2 my-6">
+ <a href="#get-overview" className="flex items-center gap-3 p-3 rounded-lg bg-fd-secondary/50 hover:bg-fd-secondary transition-colors no-underline">
+ <span className="px-2 py-1 text-xs font-bold rounded bg-green-500/20 text-green-600 dark:text-green-400">GET</span>
+ <code className="text-sm">/api/overview/:site</code>
+ </a>
+ <a href="#get-overview-time-series" className="flex items-center gap-3 p-3 rounded-lg bg-fd-secondary/50 hover:bg-fd-secondary transition-colors no-underline">
+ <span className="px-2 py-1 text-xs font-bold rounded bg-green-500/20 text-green-600 dark:text-green-400">GET</span>
+ <code className="text-sm">/api/overview/:site/bucketed</code>
+ </a>
+ <a href="#get-metric" className="flex items-center gap-3 p-3 rounded-lg bg-fd-secondary/50 hover:bg-fd-secondary transition-colors no-underline">
+ <span className="px-2 py-1 text-xs font-bold rounded bg-green-500/20 text-green-600 dark:text-green-400">GET</span>
+ <code className="text-sm">/api/metric/:site</code>
+ </a>
+ <a href="#get-live-visitors" className="flex items-center gap-3 p-3 rounded-lg bg-fd-secondary/50 hover:bg-fd-secondary transition-colors no-underline">
+ <span className="px-2 py-1 text-xs font-bold rounded bg-green-500/20 text-green-600 dark:text-green-400">GET</span>
+ <code className="text-sm">/api/live-usercount/:site</code>
+ </a>
+</div>
+
+---
+
+## Get Overview
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
```
GET /api/overview/:site
@@ -11,7 +43,7 @@ GET /api/overview/:site
Returns high-level analytics metrics for a site.
-## Path Parameters
+### Path Parameters
<TypeTable
type={{
@@ -23,11 +55,11 @@ Returns high-level analytics metrics for a site.
}}
/>
-## Query Parameters
+### Query Parameters
-Accepts all [Common Parameters](/docs/api/stats/guide#common-parameters) (time and filters).
+Accepts all [Common Parameters](/docs/api/stats/reference#common-parameters) (time and filters).
-## Response
+### Response
<TypeTable
type={{
@@ -59,16 +91,52 @@ Accepts all [Common Parameters](/docs/api/stats/guide#common-parameters) (time a
}}
/>
-## Example Request
+</div>
+<div className="flex flex-col gap-4">
-```bash
-curl -X GET "https://api.rybbit.com/api/overview/123?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
+<Tabs items={['cURL', 'JavaScript', 'Python']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/overview/123?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://api.rybbit.io/api/overview/123?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York',
+ {
+ headers: {
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+ }
+);
-## Example Response
+const data = await response.json();
+```
+ </Tab>
+ <Tab value="Python">
+```python title="Request"
+import requests
+
+response = requests.get(
+ 'https://api.rybbit.io/api/overview/123',
+ params={
+ 'start_date': '2024-01-01',
+ 'end_date': '2024-01-31',
+ 'time_zone': 'America/New_York'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
-```json
+data = response.json()
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
{
"data": {
"sessions": 15420,
@@ -80,3 +148,482 @@ curl -X GET "https://api.rybbit.com/api/overview/123?start_date=2024-01-01&end_d
}
}
```
+
+</div>
+</div>
+
+---
+
+## Get Overview (Time Series)
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/overview/:site/bucketed
+```
+
+Returns time-series analytics data broken down by configurable time buckets. Useful for charting trends over time.
+
+### Path Parameters
+
+<TypeTable
+ type={{
+ site: {
+ description: 'Site ID or site identifier',
+ type: 'string | number',
+ required: true,
+ },
+ }}
+/>
+
+### Query Parameters
+
+Accepts all [Common Parameters](/docs/api/stats/reference#common-parameters) plus the following:
+
+<TypeTable
+ type={{
+ bucket: {
+ description: 'Time bucket size for grouping data',
+ type: 'TimeBucket',
+ typeDescription: '"minute" | "five_minutes" | "ten_minutes" | "fifteen_minutes" | "hour" | "day" | "week" | "month" | "year"',
+ required: true,
+ },
+ }}
+/>
+
+#### 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
+
+<TypeTable
+ type={{
+ time: {
+ description: 'Start of the time bucket',
+ type: 'string',
+ typeDescription: 'ISO 8601 datetime',
+ },
+ 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/overview/123/bucketed?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://api.rybbit.io/api/overview/123/bucketed?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://api.rybbit.io/api/overview/123/bucketed',
+ 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>
+</Tabs>
+
+```json title="Response"
+{
+ "data": [
+ {
+ "time": "2024-01-01T00:00:00.000Z",
+ "sessions": 1250,
+ "pageviews": 3890,
+ "users": 1100,
+ "pages_per_session": 3.11,
+ "bounce_rate": 41.5,
+ "session_duration": 165.2
+ },
+ {
+ "time": "2024-01-02T00:00:00.000Z",
+ "sessions": 1420,
+ "pageviews": 4520,
+ "users": 1280,
+ "pages_per_session": 3.18,
+ "bounce_rate": 39.8,
+ "session_duration": 178.4
+ },
+ {
+ "time": "2024-01-03T00:00:00.000Z",
+ "sessions": 1380,
+ "pageviews": 4210,
+ "users": 1190,
+ "pages_per_session": 3.05,
+ "bounce_rate": 42.1,
+ "session_duration": 162.8
+ }
+ ]
+}
+```
+
+</div>
+</div>
+
+---
+
+## Get Metric
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/metric/:site
+```
+
+Returns dimensional analytics data broken down by a specific parameter. Supports pagination.
+
+### Path Parameters
+
+<TypeTable
+ type={{
+ site: {
+ description: 'Site ID or site identifier',
+ type: 'string | number',
+ required: true,
+ },
+ }}
+/>
+
+### Query Parameters
+
+Accepts all [Common Parameters](/docs/api/stats/reference#common-parameters) plus the following:
+
+<TypeTable
+ type={{
+ parameter: {
+ description: 'The dimension to break down by',
+ type: 'FilterParameter',
+ typeDescription: 'e.g., "pathname", "country", "browser", "event_name"',
+ required: true,
+ },
+ limit: {
+ description: 'Number of results per page',
+ type: 'number',
+ default: 100,
+ },
+ page: {
+ description: 'Page number (1-indexed)',
+ type: 'number',
+ default: 1,
+ },
+ }}
+/>
+
+### 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
+
+<TypeTable
+ type={{
+ value: {
+ description: 'The dimension value',
+ type: 'string',
+ typeDescription: 'e.g., "/blog", "Chrome", "US"',
+ },
+ count: {
+ description: 'Number of sessions for this value',
+ 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,
+ },
+ 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/metric/123?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://api.rybbit.io/api/metric/123?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://api.rybbit.io/api/metric/123',
+ 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>
+</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 Live Visitors
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/live-usercount/:site
+```
+
+Returns the count of unique active sessions within the specified time window. Useful for displaying real-time visitor counts.
+
+### Path Parameters
+
+<TypeTable
+ type={{
+ site: {
+ description: 'Site ID or site identifier',
+ type: 'string | number',
+ required: true,
+ },
+ }}
+/>
+
+### Query Parameters
+
+<TypeTable
+ type={{
+ minutes: {
+ description: 'Time window in minutes to count active sessions',
+ type: 'number',
+ default: 5,
+ typeDescription: 'Sessions with activity within the last N minutes are considered "live"',
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ count: {
+ description: 'Number of unique active sessions',
+ type: 'number',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/live-usercount/123?minutes=5" \
+ -H "Authorization: Bearer your_api_key_here"
+```
+ </Tab>
+ <Tab value="JavaScript">
+```javascript title="Request"
+const response = await fetch(
+ 'https://api.rybbit.io/api/live-usercount/123?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://api.rybbit.io/api/live-usercount/123',
+ params={'minutes': 5},
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+print(f"Live visitors: {data['count']}")
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
+{
+ "count": 42
+}
+```
+
+### Polling Example
+
+```javascript title="Real-time Widget"
+async function updateLiveCount() {
+ const response = await fetch(
+ 'https://api.rybbit.io/api/live-usercount/123?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>
diff --git a/docs/content/docs/api/stats/guide.mdx b/docs/content/docs/api/stats/reference.mdx
similarity index 98%
rename from docs/content/docs/api/stats/guide.mdx
rename to docs/content/docs/api/stats/reference.mdx
index dc9516960..98bba55b0 100644
--- a/docs/content/docs/api/stats/guide.mdx
+++ b/docs/content/docs/api/stats/reference.mdx
@@ -1,12 +1,10 @@
---
-title: Stats API Guide
+title: API Reference
description: Authentication, common parameters, and best practices for the Rybbit Stats API
---
import { TypeTable } from 'fumadocs-ui/components/type-table';
-The Rybbit API allows you to programmatically access your analytics data. All analytics endpoints are read-only and require authentication via API keys.
-
## Authentication
All API requests must include authentication using one of the following methods:
@@ -42,6 +40,8 @@ API keys are user-scoped and grant organization-level access:
- **500 requests per 10 minutes** per API key
- Keys are tied to your user account and grant access to all sites in your organization(s)
+---
+
## Common Parameters
The following parameters are shared across all analytics endpoints.
@@ -415,7 +415,6 @@ The `filters` parameter accepts a JSON-encoded array of filter objects to narrow
]
```
-
**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