Skip to content

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

Update Stats API documentation to include additional pages for improved navigation and resource access.

Bill Yang798a661dc343
diff --git a/docs/content/docs/api/stats/errors.mdx b/docs/content/docs/api/stats/errors.mdx
new file mode 100644
index 000000000..721cebff5
--- /dev/null
+++ b/docs/content/docs/api/stats/errors.mdx
@@ -0,0 +1,533 @@
+---
+title: Errors
+description: Track and analyze JavaScript errors captured from your 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-error-names" 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/error-names/:site</code>
+ </a>
+ <a href="#get-error-events" 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/error-events/:site</code>
+ </a>
+ <a href="#get-error-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/error-bucketed/:site</code>
+ </a>
+</div>
+
+---
+
+## Get Error Names
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/error-names/:site
+```
+
+Returns a list of unique error messages with occurrence counts and affected session counts.
+
+### 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={{
+ 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
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of error objects (or paginated wrapper)',
+ type: 'Error[] | PaginatedResponse',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/error-names/123?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://api.rybbit.io/api/error-names/123?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://api.rybbit.io/api/error-names/123',
+ params={
+ 'start_date': '2024-01-01',
+ 'end_date': '2024-01-31'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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 Events
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/error-events/:site
+```
+
+Returns individual error occurrences for a specific error message, with full context including stack traces.
+
+### 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={{
+ 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
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of error event objects',
+ type: 'ErrorEvent[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/error-events/123?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://api.rybbit.io/api/error-events/123?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://api.rybbit.io/api/error-events/123',
+ params={
+ 'errorMessage': "Cannot read property 'map' of undefined",
+ 'limit': 10
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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 Time Series
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/error-bucketed/:site
+```
+
+Returns error occurrence counts over time for a specific error message. Useful for tracking error trends and identifying when issues started.
+
+### 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={{
+ errorMessage: {
+ description: 'The error message to filter by',
+ type: 'string',
+ required: true,
+ },
+ bucket: {
+ description: 'Time bucket size for grouping data',
+ type: 'TimeBucket',
+ typeDescription: '"minute" | "five_minutes" | "hour" | "day" | "week" | "month"',
+ required: true,
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ success: {
+ description: 'Whether the request succeeded',
+ type: 'boolean',
+ },
+ data: {
+ description: 'Array of time-bucketed counts',
+ type: 'ErrorBucket[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/error-bucketed/123?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://api.rybbit.io/api/error-bucketed/123?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://api.rybbit.io/api/error-bucketed/123',
+ 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>
+</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>
diff --git a/docs/content/docs/api/stats/events.mdx b/docs/content/docs/api/stats/events.mdx
new file mode 100644
index 000000000..917de57a9
--- /dev/null
+++ b/docs/content/docs/api/stats/events.mdx
@@ -0,0 +1,644 @@
+---
+title: Events
+description: Retrieve event data including custom events, pageviews, and outbound links
+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-events" 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/events/:site</code>
+ </a>
+ <a href="#get-event-names" 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/events/names/:site</code>
+ </a>
+ <a href="#get-event-properties" 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/events/properties/:site</code>
+ </a>
+ <a href="#get-outbound-links" 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/events/outbound/:site</code>
+ </a>
+</div>
+
+---
+
+## Get Events
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/events/:site
+```
+
+Returns a paginated list of events (pageviews, custom events, and outbound clicks).
+
+### 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={{
+ page: {
+ description: 'Page number (1-indexed)',
+ type: 'number',
+ default: 1,
+ },
+ page_size: {
+ description: 'Number of results per page',
+ type: 'number',
+ default: 20,
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of event objects',
+ type: 'Event[]',
+ },
+ pagination: {
+ description: 'Pagination metadata',
+ type: 'Pagination',
+ },
+ }}
+/>
+
+#### Event Object
+
+<TypeTable
+ type={{
+ timestamp: {
+ description: 'Event timestamp',
+ type: 'string',
+ typeDescription: 'ISO 8601 datetime',
+ },
+ type: {
+ description: 'Event type',
+ type: 'string',
+ typeDescription: '"pageview" | "custom_event" | "outbound"',
+ },
+ event_name: {
+ description: 'Custom event name',
+ type: 'string',
+ },
+ properties: {
+ description: 'Event properties as JSON string',
+ type: 'string',
+ },
+ user_id: {
+ description: 'User identifier',
+ type: 'string',
+ },
+ pathname: {
+ description: 'Page path',
+ 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',
+ },
+ operating_system: {
+ description: 'Operating system',
+ type: 'string',
+ },
+ country: {
+ description: 'Country code',
+ type: 'string',
+ },
+ device_type: {
+ description: 'Device type',
+ 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://api.rybbit.io/api/events/123?page=1&page_size=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://api.rybbit.io/api/events/123?page=1&page_size=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://api.rybbit.io/api/events/123',
+ params={
+ 'page': 1,
+ 'page_size': 20,
+ 'start_date': '2024-01-01',
+ 'end_date': '2024-01-31'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
+{
+ "data": [
+ {
+ "timestamp": "2024-01-31T14:22:00.000Z",
+ "type": "custom_event",
+ "event_name": "signup",
+ "properties": "{\"plan\":\"pro\",\"source\":\"homepage\"}",
+ "user_id": "user_abc123",
+ "pathname": "/signup",
+ "hostname": "example.com",
+ "page_title": "Sign Up",
+ "browser": "Chrome",
+ "operating_system": "macOS",
+ "country": "US",
+ "device_type": "desktop"
+ },
+ {
+ "timestamp": "2024-01-31T14:21:00.000Z",
+ "type": "pageview",
+ "event_name": "",
+ "properties": "{}",
+ "user_id": "user_abc123",
+ "pathname": "/pricing",
+ "hostname": "example.com",
+ "page_title": "Pricing",
+ "browser": "Chrome",
+ "operating_system": "macOS",
+ "country": "US",
+ "device_type": "desktop"
+ }
+ ],
+ "pagination": {
+ "total": 48933,
+ "page": 1,
+ "pageSize": 20,
+ "totalPages": 2447
+ }
+}
+```
+
+</div>
+</div>
+
+---
+
+## Get Event Names
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/events/names/:site
+```
+
+Returns a list of unique custom event names with their occurrence counts.
+
+### 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) (time and filters).
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of event name objects',
+ type: 'EventName[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/events/names/123?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://api.rybbit.io/api/events/names/123?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://api.rybbit.io/api/events/names/123',
+ params={
+ 'start_date': '2024-01-01',
+ 'end_date': '2024-01-31'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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 Event Properties
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/events/properties/:site
+```
+
+Returns property key-value pairs for a specific event name with their occurrence counts.
+
+### 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={{
+ event_name: {
+ description: 'Event name to get properties for',
+ type: 'string',
+ required: true,
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of property objects',
+ type: 'EventProperty[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/events/properties/123?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://api.rybbit.io/api/events/properties/123?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://api.rybbit.io/api/events/properties/123',
+ 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>
+</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 Outbound Links
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/events/outbound/:site
+```
+
+Returns a list of outbound link clicks with their occurrence counts.
+
+### 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) (time and filters).
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of outbound link objects',
+ type: 'OutboundLink[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/events/outbound/123?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://api.rybbit.io/api/events/outbound/123?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://api.rybbit.io/api/events/outbound/123',
+ params={
+ 'start_date': '2024-01-01',
+ 'end_date': '2024-01-31'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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>
diff --git a/docs/content/docs/api/stats/funnels.mdx b/docs/content/docs/api/stats/funnels.mdx
new file mode 100644
index 000000000..f55403f33
--- /dev/null
+++ b/docs/content/docs/api/stats/funnels.mdx
@@ -0,0 +1,791 @@
+---
+title: Funnels
+description: Create and analyze multi-step conversion funnels
+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-funnels" 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/funnels/:site</code>
+ </a>
+ <a href="#analyze-funnel" 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-blue-500/20 text-blue-600 dark:text-blue-400">POST</span>
+ <code className="text-sm">/api/funnel/:site</code>
+ </a>
+ <a href="#get-funnel-step-sessions" 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-blue-500/20 text-blue-600 dark:text-blue-400">POST</span>
+ <code className="text-sm">/api/funnel/:stepNumber/sessions/:site</code>
+ </a>
+ <a href="#create-funnel" 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-blue-500/20 text-blue-600 dark:text-blue-400">POST</span>
+ <code className="text-sm">/api/funnel/create/:site</code>
+ </a>
+ <a href="#delete-funnel" 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-red-500/20 text-red-600 dark:text-red-400">DELETE</span>
+ <code className="text-sm">/api/funnel/:funnelId</code>
+ </a>
+</div>
+
+---
+
+## Get Funnels
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/funnels/:site
+```
+
+Returns all saved funnels for a site.
+
+### Path Parameters
+
+<TypeTable
+ type={{
+ site: {
+ description: 'Site ID or site identifier',
+ type: 'string | number',
+ required: true,
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of saved funnels',
+ type: 'Funnel[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/funnels/123" \
+ -H "Authorization: Bearer your_api_key_here"
+```
+ </Tab>
+ <Tab value="JavaScript">
+```javascript title="Request"
+const response = await fetch(
+ 'https://api.rybbit.io/api/funnels/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://api.rybbit.io/api/funnels/123',
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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>
+
+---
+
+## Analyze Funnel
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+POST /api/funnel/:site
+```
+
+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
+
+<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) (time and filters).
+
+### Request Body
+
+<TypeTable
+ type={{
+ steps: {
+ description: 'Array of funnel steps (minimum 2)',
+ type: 'FunnelStep[]',
+ required: true,
+ },
+ }}
+/>
+
+#### FunnelStep Object
+
+<TypeTable
+ type={{
+ type: {
+ description: 'Step type',
+ type: 'string',
+ typeDescription: '"page" | "event"',
+ 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
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of step results',
+ type: 'FunnelStepResult[]',
+ },
+ }}
+/>
+
+#### FunnelStepResult Object
+
+<TypeTable
+ type={{
+ step_number: {
+ description: 'Step number (1-indexed)',
+ type: 'number',
+ },
+ step_name: {
+ description: 'Step name',
+ type: 'string',
+ },
+ visitors: {
+ description: 'Number of sessions that reached this step',
+ type: 'number',
+ },
+ conversion_rate: {
+ description: 'Percentage of step 1 visitors who 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X POST "https://api.rybbit.io/api/funnel/123?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://api.rybbit.io/api/funnel/123?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://api.rybbit.io/api/funnel/123',
+ 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>
+</Tabs>
+
+```json title="Response"
+{
+ "data": [
+ {
+ "step_number": 1,
+ "step_name": "Homepage",
+ "visitors": 10000,
+ "conversion_rate": 100,
+ "dropoff_rate": 0
+ },
+ {
+ "step_number": 2,
+ "step_name": "Pricing",
+ "visitors": 4500,
+ "conversion_rate": 45,
+ "dropoff_rate": 55
+ },
+ {
+ "step_number": 3,
+ "step_name": "Signup",
+ "visitors": 1800,
+ "conversion_rate": 18,
+ "dropoff_rate": 60
+ },
+ {
+ "step_number": 4,
+ "step_name": "Complete",
+ "visitors": 720,
+ "conversion_rate": 7.2,
+ "dropoff_rate": 60
+ }
+ ]
+}
+```
+
+</div>
+</div>
+
+---
+
+## Get Funnel Step Sessions
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+POST /api/funnel/:stepNumber/sessions/:site
+```
+
+Returns sessions that either reached or dropped off at a specific funnel step. Useful for analyzing user behavior at each stage.
+
+### 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
+
+Accepts all [Common Parameters](/docs/api/stats/reference#common-parameters) plus the following:
+
+<TypeTable
+ type={{
+ mode: {
+ description: 'Whether to get sessions that reached or dropped off at this step',
+ type: 'string',
+ typeDescription: '"reached" | "dropped"',
+ 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
+
+<TypeTable
+ type={{
+ steps: {
+ description: 'Array of funnel steps (same as used in analyze)',
+ type: 'FunnelStep[]',
+ required: true,
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of session objects',
+ type: 'Session[]',
+ },
+ }}
+/>
+
+</div>
+<div className="flex flex-col gap-4">
+
+<Tabs items={['cURL', 'JavaScript', 'Python']}>
+ <Tab value="cURL">
+```bash title="Get sessions that dropped off at step 2"
+curl -X POST "https://api.rybbit.io/api/funnel/2/sessions/123?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://api.rybbit.io/api/funnel/3/sessions/123?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://api.rybbit.io/api/funnel/2/sessions/123',
+ 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>
+</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 Funnel
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+POST /api/funnel/create/:site
+```
+
+Creates or updates a saved funnel. If `reportId` is provided, updates the existing funnel.
+
+### Path Parameters
+
+<TypeTable
+ type={{
+ site: {
+ description: 'Site ID or site identifier',
+ type: 'string | number',
+ required: true,
+ },
+ }}
+/>
+
+### 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
+
+<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']}>
+ <Tab value="cURL">
+```bash title="Create New Funnel"
+curl -X POST "https://api.rybbit.io/api/funnel/create/123" \
+ -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://api.rybbit.io/api/funnel/create/123',
+ {
+ 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://api.rybbit.io/api/funnel/create/123',
+ 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>
+</Tabs>
+
+```json title="Response"
+{
+ "success": true,
+ "funnelId": 2
+}
+```
+
+</div>
+</div>
+
+---
+
+## Delete Funnel
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+DELETE /api/funnel/:funnelId
+```
+
+Deletes a saved funnel. This action cannot be undone.
+
+### Path Parameters
+
+<TypeTable
+ type={{
+ funnelId: {
+ description: 'ID of the funnel to delete',
+ type: 'string | number',
+ required: true,
+ },
+ }}
+/>
+
+### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X DELETE "https://api.rybbit.io/api/funnel/1" \
+ -H "Authorization: Bearer your_api_key_here"
+```
+ </Tab>
+ <Tab value="JavaScript">
+```javascript title="Request"
+const response = await fetch(
+ 'https://api.rybbit.io/api/funnel/1',
+ {
+ 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://api.rybbit.io/api/funnel/1',
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
+{
+ "success": true
+}
+```
+
+</div>
+</div>
diff --git a/docs/content/docs/api/stats/goals.mdx b/docs/content/docs/api/stats/goals.mdx
new file mode 100644
index 000000000..acfa87e07
--- /dev/null
+++ b/docs/content/docs/api/stats/goals.mdx
@@ -0,0 +1,844 @@
+---
+title: Goals
+description: Create and track conversion goals based on page visits or custom events
+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-goals" 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/goals/:site</code>
+ </a>
+ <a href="#get-goal-sessions" 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/goals/:goalId/sessions/:site</code>
+ </a>
+ <a href="#create-goal" 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-blue-500/20 text-blue-600 dark:text-blue-400">POST</span>
+ <code className="text-sm">/api/goal/create</code>
+ </a>
+ <a href="#update-goal" 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-yellow-500/20 text-yellow-600 dark:text-yellow-400">PUT</span>
+ <code className="text-sm">/api/goal/update</code>
+ </a>
+ <a href="#delete-goal" 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-red-500/20 text-red-600 dark:text-red-400">DELETE</span>
+ <code className="text-sm">/api/goal/:goalId</code>
+ </a>
+</div>
+
+---
+
+## Get Goals
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/goals/:site
+```
+
+Returns a paginated list of goals with their conversion metrics.
+
+### 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={{
+ 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: '"goalId" | "name" | "goalType" | "createdAt"',
+ default: 'createdAt',
+ },
+ order: {
+ description: 'Sort direction',
+ type: 'string',
+ typeDescription: '"asc" | "desc"',
+ default: 'desc',
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of goal objects with conversion data',
+ type: 'Goal[]',
+ },
+ meta: {
+ description: 'Pagination metadata',
+ type: 'PaginationMeta',
+ },
+ }}
+/>
+
+#### 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: '"path" | "event"',
+ },
+ 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
+
+<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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/goals/123?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://api.rybbit.io/api/goals/123?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://api.rybbit.io/api/goals/123',
+ params={
+ 'start_date': '2024-01-01',
+ 'end_date': '2024-01-31'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/goals/:goalId/sessions/:site
+```
+
+Returns sessions that completed a specific goal. Useful for analyzing the behavior of converting users.
+
+### 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
+
+Accepts all [Common Parameters](/docs/api/stats/reference#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
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of session objects',
+ type: 'Session[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/goals/1/sessions/123?page=1&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/goals/1/sessions/123?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://api.rybbit.io/api/goals/1/sessions/123',
+ params={
+ 'page': 1,
+ 'limit': 10
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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>
+
+---
+
+## Create Goal
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+POST /api/goal/create
+```
+
+Creates a new goal for tracking conversions.
+
+### Request Body
+
+<TypeTable
+ type={{
+ siteId: {
+ description: 'Site ID to create the goal for',
+ type: 'number',
+ required: true,
+ },
+ name: {
+ description: 'Goal name',
+ type: 'string',
+ required: false,
+ },
+ goalType: {
+ description: 'Type of goal',
+ type: 'string',
+ typeDescription: '"path" | "event"',
+ required: true,
+ },
+ config: {
+ description: 'Goal configuration',
+ type: 'GoalConfig',
+ required: true,
+ },
+ }}
+/>
+
+#### GoalConfig for Path Goals
+
+<TypeTable
+ type={{
+ pathPattern: {
+ description: 'URL path pattern to match. Supports wildcards (*)',
+ type: 'string',
+ required: true,
+ typeDescription: 'e.g., "/checkout/*", "/signup/complete"',
+ },
+ }}
+/>
+
+#### 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
+
+<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']}>
+ <Tab value="cURL">
+```bash title="Path Goal"
+curl -X POST "https://api.rybbit.io/api/goal/create" \
+ -H "Authorization: Bearer your_api_key_here" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "siteId": 123,
+ "name": "Checkout Complete",
+ "goalType": "path",
+ "config": {
+ "pathPattern": "/checkout/success"
+ }
+ }'
+```
+ </Tab>
+ <Tab value="JavaScript">
+```javascript title="Event Goal"
+const response = await fetch(
+ 'https://api.rybbit.io/api/goal/create',
+ {
+ method: 'POST',
+ headers: {
+ 'Authorization': 'Bearer your_api_key_here',
+ 'Content-Type': 'application/json'
+ },
+ body: JSON.stringify({
+ siteId: 123,
+ 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://api.rybbit.io/api/goal/create',
+ json={
+ 'siteId': 123,
+ 'name': 'Signup Complete',
+ 'goalType': 'path',
+ 'config': {
+ 'pathPattern': '/signup/*'
+ }
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
+{
+ "success": true,
+ "goalId": 3
+}
+```
+
+</div>
+</div>
+
+---
+
+## Update Goal
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+PUT /api/goal/update
+```
+
+Updates an existing goal.
+
+### Request Body
+
+<TypeTable
+ type={{
+ goalId: {
+ description: 'ID of the goal to update',
+ type: 'number',
+ required: true,
+ },
+ siteId: {
+ description: 'Site ID the goal belongs to',
+ type: 'number',
+ required: true,
+ },
+ name: {
+ description: 'Updated goal name',
+ type: 'string',
+ required: false,
+ },
+ goalType: {
+ description: 'Type of goal',
+ type: 'string',
+ typeDescription: '"path" | "event"',
+ required: true,
+ },
+ config: {
+ description: 'Updated goal configuration',
+ type: 'GoalConfig',
+ required: true,
+ },
+ }}
+/>
+
+### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X PUT "https://api.rybbit.io/api/goal/update" \
+ -H "Authorization: Bearer your_api_key_here" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "goalId": 1,
+ "siteId": 123,
+ "name": "Signup Completed (Updated)",
+ "goalType": "path",
+ "config": {
+ "pathPattern": "/signup/complete/*"
+ }
+ }'
+```
+ </Tab>
+ <Tab value="JavaScript">
+```javascript title="Request"
+const response = await fetch(
+ 'https://api.rybbit.io/api/goal/update',
+ {
+ method: 'PUT',
+ headers: {
+ 'Authorization': 'Bearer your_api_key_here',
+ 'Content-Type': 'application/json'
+ },
+ body: JSON.stringify({
+ goalId: 1,
+ siteId: 123,
+ 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://api.rybbit.io/api/goal/update',
+ json={
+ 'goalId': 1,
+ 'siteId': 123,
+ 'name': 'Signup Completed (Updated)',
+ 'goalType': 'path',
+ 'config': {
+ 'pathPattern': '/signup/complete/*'
+ }
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
+{
+ "success": true,
+ "goalId": 1
+}
+```
+
+</div>
+</div>
+
+---
+
+## Delete Goal
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+DELETE /api/goal/:goalId
+```
+
+Deletes a goal. This action cannot be undone.
+
+### Path Parameters
+
+<TypeTable
+ type={{
+ goalId: {
+ description: 'ID of the goal to delete',
+ type: 'string | number',
+ required: true,
+ },
+ }}
+/>
+
+### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X DELETE "https://api.rybbit.io/api/goal/1" \
+ -H "Authorization: Bearer your_api_key_here"
+```
+ </Tab>
+ <Tab value="JavaScript">
+```javascript title="Request"
+const response = await fetch(
+ 'https://api.rybbit.io/api/goal/1',
+ {
+ 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://api.rybbit.io/api/goal/1',
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
+{
+ "success": true
+}
+```
+
+</div>
+</div>
diff --git a/docs/content/docs/api/stats/meta.json b/docs/content/docs/api/stats/meta.json
index ea383fa51..f8417977c 100644
--- a/docs/content/docs/api/stats/meta.json
+++ b/docs/content/docs/api/stats/meta.json
@@ -1,4 +1,4 @@
{
"title": "Stats",
- "pages": ["reference", "overview"]
+ "pages": ["reference", "overview", "sessions", "events", "users", "goals", "funnels", "performance", "errors", "misc"]
}
diff --git a/docs/content/docs/api/stats/misc.mdx b/docs/content/docs/api/stats/misc.mdx
new file mode 100644
index 000000000..7dbf5ef89
--- /dev/null
+++ b/docs/content/docs/api/stats/misc.mdx
@@ -0,0 +1,438 @@
+---
+title: Misc
+description: Retention analysis and user journey tracking endpoints
+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-retention" 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/retention/:site</code>
+ </a>
+ <a href="#get-journeys" 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/journeys/:site</code>
+ </a>
+</div>
+
+---
+
+## Get Retention
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/retention/:site
+```
+
+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
+
+<TypeTable
+ type={{
+ site: {
+ description: 'Site ID or site identifier',
+ type: 'string | number',
+ required: true,
+ },
+ }}
+/>
+
+### Query Parameters
+
+<TypeTable
+ type={{
+ mode: {
+ description: 'Retention period granularity',
+ type: 'string',
+ typeDescription: '"day" | "week"',
+ default: 'week',
+ },
+ range: {
+ description: 'Number of days to analyze (7-365)',
+ type: 'number',
+ default: 90,
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Retention analysis data',
+ type: 'RetentionData',
+ },
+ }}
+/>
+
+#### 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: '"day" | "week"',
+ },
+ range: {
+ description: 'Time range in days',
+ type: 'number',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/retention/123?mode=week&range=90" \
+ -H "Authorization: Bearer your_api_key_here"
+```
+ </Tab>
+ <Tab value="JavaScript">
+```javascript title="Request"
+const response = await fetch(
+ 'https://api.rybbit.io/api/retention/123?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://api.rybbit.io/api/retention/123',
+ params={
+ 'mode': 'week',
+ 'range': 90
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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
+
+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
+
+```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>
+
+---
+
+## Get Journeys
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/journeys/:site
+```
+
+Returns the most common page navigation paths (user journeys) within sessions. Useful for understanding how users navigate through your site.
+
+### 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={{
+ 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., {"0": "/"})',
+ type: 'string',
+ typeDescription: 'JSON string mapping step index to required path',
+ required: false,
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ journeys: {
+ description: 'Array of journey objects',
+ type: 'Journey[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/journeys/123?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://api.rybbit.io/api/journeys/123?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://api.rybbit.io/api/journeys/123',
+ 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>
+</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
+
+You can filter journeys that include specific pages at specific steps:
+
+<Tabs items={['cURL', 'JavaScript']}>
+ <Tab value="cURL">
+```bash title="Filter journeys starting from homepage"
+curl -X GET "https://api.rybbit.io/api/journeys/123?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://api.rybbit.io/api/journeys/123?steps=3&stepFilters=${encodeURIComponent(stepFilters)}`,
+ {
+ headers: {
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+ }
+);
+```
+ </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>
diff --git a/docs/content/docs/api/stats/performance.mdx b/docs/content/docs/api/stats/performance.mdx
new file mode 100644
index 000000000..c97b2c1f4
--- /dev/null
+++ b/docs/content/docs/api/stats/performance.mdx
@@ -0,0 +1,542 @@
+---
+title: Performance
+description: Retrieve Core Web Vitals and performance metrics for your 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.
+
+## Core Web Vitals
+
+The performance endpoints return data for the following Core Web Vitals metrics:
+
+| Metric | Description | Good | Needs Improvement | Poor |
+|--------|-------------|------|-------------------|------|
+| **LCP** | Largest Contentful Paint - loading performance | < 2.5s | 2.5s - 4s | > 4s |
+| **CLS** | Cumulative Layout Shift - visual stability | < 0.1 | 0.1 - 0.25 | > 0.25 |
+| **INP** | Interaction to Next Paint - interactivity | < 200ms | 200ms - 500ms | > 500ms |
+| **FCP** | First Contentful Paint - initial render | < 1.8s | 1.8s - 3s | > 3s |
+| **TTFB** | Time to First Byte - server response time | < 800ms | 800ms - 1.8s | > 1.8s |
+
+## Endpoints
+
+<div className="flex flex-col gap-2 my-6">
+ <a href="#get-performance-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/performance/overview/:site</code>
+ </a>
+ <a href="#get-performance-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/performance/time-series/:site</code>
+ </a>
+ <a href="#get-performance-by-dimension" 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/performance/by-dimension/:site</code>
+ </a>
+</div>
+
+---
+
+## Get Performance Overview
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/performance/overview/:site
+```
+
+Returns aggregate performance metrics with percentile breakdowns for all Core Web Vitals.
+
+### 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) (time and filters).
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Performance metrics object',
+ type: 'PerformanceMetrics',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/performance/overview/123?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://api.rybbit.io/api/performance/overview/123?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://api.rybbit.io/api/performance/overview/123',
+ params={
+ 'start_date': '2024-01-01',
+ 'end_date': '2024-01-31'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/performance/time-series/:site
+```
+
+Returns performance metrics over time, broken down by configurable time buckets. Useful for charting performance trends.
+
+### 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" | "hour" | "day" | "week" | "month"',
+ required: true,
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of time-bucketed performance data',
+ type: 'PerformancePoint[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/performance/time-series/123?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://api.rybbit.io/api/performance/time-series/123?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://api.rybbit.io/api/performance/time-series/123',
+ 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>
+</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>
+
+---
+
+## Get Performance by Dimension
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/performance/by-dimension/:site
+```
+
+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
+
+<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={{
+ dimension: {
+ description: 'Dimension to break down by',
+ type: 'string',
+ typeDescription: '"pathname" | "country" | "device_type" | "browser" | "operating_system" | "region"',
+ 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: '"asc" | "desc"',
+ default: 'desc',
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Paginated response object',
+ type: 'PaginatedResponse',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/performance/by-dimension/123?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://api.rybbit.io/api/performance/by-dimension/123?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://api.rybbit.io/api/performance/by-dimension/123',
+ params={
+ 'dimension': 'pathname',
+ 'sort_by': 'lcp_p75',
+ 'sort_order': 'desc',
+ 'limit': 10
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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>
diff --git a/docs/content/docs/api/stats/sessions.mdx b/docs/content/docs/api/stats/sessions.mdx
new file mode 100644
index 000000000..c8d36fba0
--- /dev/null
+++ b/docs/content/docs/api/stats/sessions.mdx
@@ -0,0 +1,621 @@
+---
+title: Sessions
+description: Retrieve session-level analytics data including session lists, details, and locations
+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-sessions" 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/sessions/:site</code>
+ </a>
+ <a href="#get-session" 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/session/:sessionId/:site</code>
+ </a>
+ <a href="#get-session-locations" 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/session-locations/:site</code>
+ </a>
+</div>
+
+---
+
+## Get Sessions
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/sessions/:site
+```
+
+Returns a paginated list of sessions with their analytics data.
+
+### 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={{
+ 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: '"true" | "false"',
+ default: 'false',
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of session objects',
+ type: 'Session[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/sessions/123?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://api.rybbit.io/api/sessions/123?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://api.rybbit.io/api/sessions/123',
+ 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>
+</Tabs>
+
+```json title="Response"
+{
+ "data": [
+ {
+ "session_id": "sess_abc123",
+ "user_id": "dev_xyz789",
+ "identified_user_id": "[email protected]",
+ "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
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/session/:sessionId/:site
+```
+
+Returns detailed information about a specific session including all events and pageviews.
+
+### 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
+
+<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
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Session details object',
+ type: 'SessionDetails',
+ },
+ }}
+/>
+
+#### 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
+
+<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: '"pageview" | "custom_event" | "error" | "outbound"',
+ },
+ 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/session/sess_abc123/123?limit=50" \
+ -H "Authorization: Bearer your_api_key_here"
+```
+ </Tab>
+ <Tab value="JavaScript">
+```javascript title="Request"
+const response = await fetch(
+ 'https://api.rybbit.io/api/session/sess_abc123/123?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://api.rybbit.io/api/session/sess_abc123/123',
+ params={'limit': 50},
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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 Session Locations
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/session-locations/:site
+```
+
+Returns aggregated session locations with coordinates for map visualization.
+
+### 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) (time and filters).
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of location objects',
+ type: 'Location[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/session-locations/123?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://api.rybbit.io/api/session-locations/123?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://api.rybbit.io/api/session-locations/123',
+ params={
+ 'start_date': '2024-01-01',
+ 'end_date': '2024-01-31'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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>
diff --git a/docs/content/docs/api/stats/users.mdx b/docs/content/docs/api/stats/users.mdx
new file mode 100644
index 000000000..ad38dd30e
--- /dev/null
+++ b/docs/content/docs/api/stats/users.mdx
@@ -0,0 +1,844 @@
+---
+title: Users
+description: Retrieve user-level analytics data including user lists, sessions, and profiles
+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-users" 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/users/:site</code>
+ </a>
+ <a href="#get-user-sessions" 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/user/:userId/sessions/:site</code>
+ </a>
+ <a href="#get-user-session-count" 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/user/session-count/:site</code>
+ </a>
+ <a href="#get-user-info" 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/user/info/:userId/:site</code>
+ </a>
+</div>
+
+---
+
+## Get Users
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/users/:site
+```
+
+Returns a paginated list of users with their analytics data. Supports filtering by identified users only.
+
+### 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={{
+ page: {
+ description: 'Page number (1-indexed)',
+ type: 'number',
+ default: 1,
+ },
+ page_size: {
+ description: 'Number of results per page',
+ type: 'number',
+ default: 20,
+ },
+ sort_by: {
+ description: 'Field to sort by',
+ type: 'string',
+ typeDescription: '"first_seen" | "last_seen" | "pageviews" | "sessions" | "events"',
+ default: 'last_seen',
+ },
+ sort_order: {
+ description: 'Sort direction',
+ type: 'string',
+ typeDescription: '"asc" | "desc"',
+ default: 'desc',
+ },
+ identified_only: {
+ description: 'Only return users with a custom identified_user_id',
+ type: 'string',
+ typeDescription: '"true" | "false"',
+ default: 'false',
+ },
+ }}
+/>
+
+### 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
+
+<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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/users/123?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://api.rybbit.io/api/users/123?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://api.rybbit.io/api/users/123',
+ params={
+ 'page': 1,
+ 'page_size': 10,
+ 'sort_by': 'last_seen',
+ 'sort_order': 'desc'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
+{
+ "data": [
+ {
+ "user_id": "abc123def456",
+ "identified_user_id": "[email protected]",
+ "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 Sessions
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/user/:userId/sessions/:site
+```
+
+Returns all sessions for a specific user, grouped with their pageviews. Useful for viewing a user's browsing history and behavior patterns.
+
+### 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,
+ },
+ }}
+/>
+
+### Query Parameters
+
+Accepts all [Common Parameters](/docs/api/stats/reference#common-parameters) (time and filters).
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of session objects',
+ type: 'Session[]',
+ },
+ }}
+/>
+
+#### Session Object
+
+<TypeTable
+ type={{
+ session_id: {
+ description: 'Unique session identifier',
+ type: 'string',
+ },
+ browser: {
+ description: 'Browser name',
+ type: 'string',
+ },
+ operating_system: {
+ description: 'Operating system name',
+ type: 'string',
+ },
+ device_type: {
+ description: 'Device type',
+ type: 'string',
+ },
+ country: {
+ description: 'Country code',
+ type: 'string',
+ },
+ firstTimestamp: {
+ description: 'Session start time',
+ type: 'string',
+ typeDescription: 'ISO 8601 datetime',
+ },
+ lastTimestamp: {
+ description: 'Session end time',
+ type: 'string',
+ typeDescription: 'ISO 8601 datetime',
+ },
+ duration: {
+ description: 'Session duration in seconds',
+ type: 'number',
+ },
+ pageviews: {
+ description: 'Array of pageviews in this session',
+ type: 'Pageview[]',
+ },
+ }}
+/>
+
+#### Pageview Object
+
+<TypeTable
+ type={{
+ pathname: {
+ description: 'Page path',
+ type: 'string',
+ },
+ querystring: {
+ description: 'Query string parameters',
+ type: 'string',
+ },
+ title: {
+ description: 'Page title',
+ type: 'string',
+ },
+ timestamp: {
+ description: 'Pageview timestamp',
+ type: 'string',
+ typeDescription: 'ISO 8601 datetime',
+ },
+ referrer: {
+ description: 'Referrer URL',
+ 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://api.rybbit.io/api/user/abc123def456/sessions/123?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://api.rybbit.io/api/user/abc123def456/sessions/123?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://api.rybbit.io/api/user/abc123def456/sessions/123',
+ params={
+ 'start_date': '2024-01-01',
+ 'end_date': '2024-01-31'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
+{
+ "data": [
+ {
+ "session_id": "sess_abc123",
+ "browser": "Chrome",
+ "operating_system": "macOS",
+ "device_type": "desktop",
+ "country": "US",
+ "firstTimestamp": "2024-01-31T14:00:00.000Z",
+ "lastTimestamp": "2024-01-31T14:22:00.000Z",
+ "duration": 1320,
+ "pageviews": [
+ {
+ "pathname": "/pricing",
+ "querystring": "",
+ "title": "Pricing - Example",
+ "timestamp": "2024-01-31T14:22:00.000Z",
+ "referrer": ""
+ },
+ {
+ "pathname": "/features",
+ "querystring": "",
+ "title": "Features - Example",
+ "timestamp": "2024-01-31T14:10:00.000Z",
+ "referrer": ""
+ },
+ {
+ "pathname": "/",
+ "querystring": "utm_source=google",
+ "title": "Home - Example",
+ "timestamp": "2024-01-31T14:00:00.000Z",
+ "referrer": "https://google.com"
+ }
+ ]
+ }
+ ]
+}
+```
+
+</div>
+</div>
+
+---
+
+## Get User Session Count
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/user/session-count/:site
+```
+
+Returns the number of sessions per day for a specific user. Useful for visualizing user engagement over time.
+
+### Path Parameters
+
+<TypeTable
+ type={{
+ site: {
+ description: 'Site ID or site identifier',
+ type: 'string | number',
+ required: true,
+ },
+ }}
+/>
+
+### 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., "America/New_York")',
+ },
+ }}
+/>
+
+### Response
+
+<TypeTable
+ type={{
+ data: {
+ description: 'Array of daily session counts',
+ type: 'DailyCount[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/user/session-count/123?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://api.rybbit.io/api/user/session-count/123?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://api.rybbit.io/api/user/session-count/123',
+ params={
+ 'user_id': 'abc123def456',
+ 'time_zone': 'America/New_York'
+ },
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </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>
+
+---
+
+## Get User Info
+
+<div className="grid grid-cols-1 xl:grid-cols-2 gap-8">
+<div>
+
+```
+GET /api/user/info/:userId/:site
+```
+
+Returns detailed information about a specific user, including their profile traits and linked devices.
+
+### 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
+
+<TypeTable
+ type={{
+ data: {
+ description: 'User info object',
+ type: 'UserInfo',
+ },
+ }}
+/>
+
+#### 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',
+ },
+ linked_devices: {
+ description: 'Devices linked to this identified user',
+ type: 'LinkedDevice[]',
+ },
+ }}
+/>
+
+#### 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']}>
+ <Tab value="cURL">
+```bash title="Request"
+curl -X GET "https://api.rybbit.io/api/user/info/[email protected]/123" \
+ -H "Authorization: Bearer your_api_key_here"
+```
+ </Tab>
+ <Tab value="JavaScript">
+```javascript title="Request"
+const response = await fetch(
+ 'https://api.rybbit.io/api/user/info/[email protected]/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://api.rybbit.io/api/user/info/[email protected]/123',
+ headers={
+ 'Authorization': 'Bearer your_api_key_here'
+ }
+)
+
+data = response.json()
+```
+ </Tab>
+</Tabs>
+
+```json title="Response"
+{
+ "data": {
+ "user_id": "abc123def456",
+ "identified_user_id": "[email protected]",
+ "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",
+ "linked_devices": [
+ {
+ "anonymous_id": "xyz789ghi012",
+ "created_at": "2024-01-20T08:15:00.000Z"
+ }
+ ]
+ }
+}
+```
+
+</div>
+</div>