Realtime Visitors

​

Endpoint

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

​

Authentication

Authorization: Bearer YOUR_API_KEY

​

Query Parameters

​

Response

​

Examples

​

Get Current Visitors

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

17

​

Polling for Updates

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

• 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

​

Common Errors

{
  "error": "Invalid API key"
}

{
  "error": "Missing site_id parameter"
}

{
  "error": "Site not found"
}