--- title: Insights description: The Insights API provides access to website analytics data including metrics, page views, visitor statistics, and detailed breakdowns by various dimensions. --- ## Authentication To authenticate with the Insights API, you need to use your `clientId` and `clientSecret`. Make sure your client has `read` or `root` mode. The default client does not have access to the Insights API. For detailed authentication information, see the [Authentication](/docs/api/authentication) guide. Include the following headers with your requests: - `openpanel-client-id`: Your OpenPanel client ID - `openpanel-client-secret`: Your OpenPanel client secret ## Base URL All Insights API requests should be made to: ``` https://api.openpanel.dev/insights ``` ## Common Query Parameters Most endpoints support the following query parameters: | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | `startDate` | string | Start date (ISO format: YYYY-MM-DD) | Based on range | | `endDate` | string | End date (ISO format: YYYY-MM-DD) | Based on range | | `range` | string | Predefined date range (`7d`, `30d`, `90d`, etc.) | `7d` | | `filters` | array | Event filters to apply | `[]` | | `cursor` | number | Page number for pagination | `1` | | `limit` | number | Number of results per page (max: 50) | `10` | ### Filter Configuration Filters can be applied to narrow down results. Each filter has the following structure: ```json { "name": "property_name", "operator": "is|isNot|contains|doesNotContain|startsWith|endsWith|regex", "value": ["value1", "value2"] } ``` ## Endpoints ### Get Metrics Retrieve comprehensive website metrics including visitors, sessions, page views, and engagement data. ``` GET /insights/{projectId}/metrics ``` #### Query Parameters | Parameter | Type | Description | Example | |-----------|------|-------------|---------| | `startDate` | string | Start date for metrics | `2024-01-01` | | `endDate` | string | End date for metrics | `2024-01-31` | | `range` | string | Predefined range | `7d` | | `filters` | array | Event filters | `[{"name":"path","operator":"is","value":["/home"]}]` | #### Example Request ```bash curl 'https://api.openpanel.dev/insights/abc123/metrics?range=30d&filters=[{"name":"path","operator":"contains","value":["/product"]}]' \ -H 'openpanel-client-id: YOUR_CLIENT_ID' \ -H 'openpanel-client-secret: YOUR_CLIENT_SECRET' ``` #### Response ```json { "metrics": { "bounce_rate": 45.2, "unique_visitors": 1250, "total_sessions": 1580, "avg_session_duration": 185.5, "total_screen_views": 4230, "views_per_session": 2.67 }, "series": [ { "date": "2024-01-01T00:00:00.000Z", "bounce_rate": 42.1, "unique_visitors": 85, "total_sessions": 98, "avg_session_duration": 195.2, "total_screen_views": 156, "views_per_session": 1.59 } ] } ``` ### Get Live Visitors Get the current number of active visitors on your website in real-time. ``` GET /insights/{projectId}/live ``` #### Example Request ```bash curl 'https://api.openpanel.dev/insights/abc123/live' \ -H 'openpanel-client-id: YOUR_CLIENT_ID' \ -H 'openpanel-client-secret: YOUR_CLIENT_SECRET' ``` #### Response ```json { "visitors": 23 } ``` ### Get Top Pages Retrieve the most visited pages with detailed analytics including session count, bounce rate, and average time on page. ``` GET /insights/{projectId}/pages ``` #### Query Parameters | Parameter | Type | Description | Example | |-----------|------|-------------|---------| | `startDate` | string | Start date | `2024-01-01` | | `endDate` | string | End date | `2024-01-31` | | `range` | string | Predefined range | `7d` | | `filters` | array | Event filters | `[]` | | `cursor` | number | Page number | `1` | | `limit` | number | Results per page (max: 50) | `10` | #### Example Request ```bash curl 'https://api.openpanel.dev/insights/abc123/pages?range=7d&limit=20' \ -H 'openpanel-client-id: YOUR_CLIENT_ID' \ -H 'openpanel-client-secret: YOUR_CLIENT_SECRET' ``` #### Response ```json [ { "title": "Homepage - Example Site", "origin": "https://example.com", "path": "/", "sessions": 456, "bounce_rate": 35.2, "avg_duration": 125.8 }, { "title": "About Us", "origin": "https://example.com", "path": "/about", "sessions": 234, "bounce_rate": 45.1, "avg_duration": 89.3 } ] ``` ### Get Referrer Data Retrieve referrer analytics to understand where your traffic is coming from. ``` GET /insights/{projectId}/referrer GET /insights/{projectId}/referrer_name GET /insights/{projectId}/referrer_type ``` #### Example Request ```bash curl 'https://api.openpanel.dev/insights/abc123/referrer?range=30d&limit=15' \ -H 'openpanel-client-id: YOUR_CLIENT_ID' \ -H 'openpanel-client-secret: YOUR_CLIENT_SECRET' ``` #### Response ```json [ { "name": "google.com", "sessions": 567, "bounce_rate": 42.1, "avg_session_duration": 156.7 }, { "name": "facebook.com", "sessions": 234, "bounce_rate": 38.9, "avg_session_duration": 189.2 } ] ``` ### Get UTM Campaign Data Analyze your marketing campaigns with UTM parameter breakdowns. ``` GET /insights/{projectId}/utm_source GET /insights/{projectId}/utm_medium GET /insights/{projectId}/utm_campaign GET /insights/{projectId}/utm_term GET /insights/{projectId}/utm_content ``` #### Example Request ```bash curl 'https://api.openpanel.dev/insights/abc123/utm_source?range=30d' \ -H 'openpanel-client-id: YOUR_CLIENT_ID' \ -H 'openpanel-client-secret: YOUR_CLIENT_SECRET' ``` #### Response ```json [ { "name": "google", "sessions": 890, "bounce_rate": 35.4, "avg_session_duration": 178.9 }, { "name": "facebook", "sessions": 456, "bounce_rate": 41.2, "avg_session_duration": 142.3 } ] ``` ### Get Geographic Data Understand your audience location with country, region, and city breakdowns. ``` GET /insights/{projectId}/country GET /insights/{projectId}/region GET /insights/{projectId}/city ``` #### Example Request ```bash curl 'https://api.openpanel.dev/insights/abc123/country?range=30d&limit=20' \ -H 'openpanel-client-id: YOUR_CLIENT_ID' \ -H 'openpanel-client-secret: YOUR_CLIENT_SECRET' ``` #### Response ```json [ { "name": "United States", "sessions": 1234, "bounce_rate": 38.7, "avg_session_duration": 167.4 }, { "name": "United Kingdom", "sessions": 567, "bounce_rate": 42.1, "avg_session_duration": 145.8 } ] ``` For region and city endpoints, an additional `prefix` field may be included: ```json [ { "prefix": "United States", "name": "California", "sessions": 456, "bounce_rate": 35.2, "avg_session_duration": 172.1 } ] ``` ### Get Device & Technology Data Analyze visitor devices, browsers, and operating systems. ``` GET /insights/{projectId}/device GET /insights/{projectId}/browser GET /insights/{projectId}/browser_version GET /insights/{projectId}/os GET /insights/{projectId}/os_version GET /insights/{projectId}/brand GET /insights/{projectId}/model ``` #### Example Request ```bash curl 'https://api.openpanel.dev/insights/abc123/browser?range=7d' \ -H 'openpanel-client-id: YOUR_CLIENT_ID' \ -H 'openpanel-client-secret: YOUR_CLIENT_SECRET' ``` #### Response ```json [ { "name": "Chrome", "sessions": 789, "bounce_rate": 36.4, "avg_session_duration": 162.3 }, { "name": "Firefox", "sessions": 234, "bounce_rate": 41.7, "avg_session_duration": 148.9 } ] ``` For version-specific endpoints (browser_version, os_version), a `prefix` field shows the parent: ```json [ { "prefix": "Chrome", "name": "118.0.0.0", "sessions": 456, "bounce_rate": 35.8, "avg_session_duration": 165.7 } ] ``` ## Error Handling The API uses standard HTTP response codes. Common error responses: ### 400 Bad Request ```json { "error": "Bad Request", "message": "Invalid query parameters", "details": { "issues": [ { "path": ["range"], "message": "Invalid enum value" } ] } } ``` ### 401 Unauthorized ```json { "error": "Unauthorized", "message": "Invalid client credentials" } ``` ### 429 Too Many Requests Rate limiting response includes headers indicating your rate limit status. ## Rate Limiting The Insights API implements rate limiting: - **100 requests per 10 seconds** per client - Rate limit headers included in responses - Implement exponential backoff for retries ## Notes - All dates are returned in ISO 8601 format - Durations are in seconds - Bounce rates and percentages are returned as decimal numbers (e.g., 45.2 = 45.2%) - Session duration is the average time spent on the website - All timezone handling is done server-side based on project settings