Insights

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 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:

{
  "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

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

{
  "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

curl 'https://api.openpanel.dev/insights/abc123/live' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'

Response

{
  "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

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

[
  {
    "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

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

[
  {
    "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

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

[
  {
    "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

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

[
  {
    "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:

[
  {
    "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

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

[
  {
    "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:

[
  {
    "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

{
  "error": "Bad Request",
  "message": "Invalid query parameters",
  "details": {
    "issues": [
      {
        "path": ["range"],
        "message": "Invalid enum value"
      }
    ]
  }
}

401 Unauthorized

{
  "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

On this page