🐸 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.jsonindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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>