Realtime Visitors

Get the current number of active visitors on your site in real-time

The realtime visitors endpoint returns the number of people currently on your site. A visitor is considered active if they triggered an event (pageview or custom event) within the last 5 minutes.

Endpoint

GET https://plausible.io/api/v1/stats/realtime/visitors

Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

site_id · string · required

The domain of your site as configured in Plausible. Example: example.com

Response

The endpoint returns a single integer representing the number of current active visitors.

response · integer

The number of visitors who have triggered an event in the last 5 minutes.

Examples

Get Current Visitors

cURL

curl "https://plausible.io/api/v1/stats/realtime/visitors?site_id=example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

17

Polling for Updates

For real-time dashboards, you can poll this endpoint at regular intervals:

JavaScript

// Poll every 30 seconds
setInterval(async () => {
  const response = await fetch(
    'https://plausible.io/api/v1/stats/realtime/visitors?site_id=example.com',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  const visitors = await response.json();
  
  // Update your UI
  document.getElementById('current-visitors').textContent = visitors;
}, 30000);

Implementation Details

• A visitor is counted as “active” if they triggered any event (excluding internal engagement events) within the last 5 minutes from the current UTC time.
• The count represents unique visitors based on their user_id, so multiple pageviews from the same visitor within the 5-minute window are counted only once.
• The endpoint queries the events_v2 table in ClickHouse with a timestamp filter for the last 5 minutes.
• There are no filters, date ranges, or comparison options for this endpoint - it always returns the current count.

Use Cases

• Real-time dashboards - Display current visitor count on admin dashboards
• Traffic monitoring - Monitor traffic spikes or unusual activity
• Social proof - Show potential customers how many people are currently browsing (e.g., “23 people are viewing this page”)
• Load monitoring - Track traffic levels to anticipate server load
• Marketing campaigns - Monitor immediate impact of campaigns or product launches

Rate Limiting

While this endpoint is designed for real-time updates, avoid excessive polling:

• Recommended polling interval: 30-60 seconds
• The data is already aggregated over 5 minutes, so polling more frequently than every 30 seconds provides limited additional value
• Check your API plan for rate limits

Error Responses

error · string

Error message describing what went wrong

Common Errors

401 Unauthorized - Invalid or missing API key

{
  "error": "Invalid API key"
}

400 Bad Request - Missing site_id parameter

{
  "error": "Missing site_id parameter"
}

404 Not Found - Site not found

{
  "error": "Site not found"
}