> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/plausible/analytics/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField query="site_id" type="string" required>
  The domain of your site as configured in Plausible. Example: `example.com`
</ParamField>

## Response

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

<ResponseField name="response" type="integer">
  The number of visitors who have triggered an event in the last 5 minutes.
</ResponseField>

## Examples

### Get Current Visitors

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://plausible.io/api/v1/stats/realtime/visitors?site_id=example.com" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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();
  console.log(`Current visitors: ${visitors}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://plausible.io/api/v1/stats/realtime/visitors',
      params={'site_id': 'example.com'},
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )
  visitors = response.json()
  print(f'Current visitors: {visitors}')
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://plausible.io/api/v1/stats/realtime/visitors?site_id=example.com');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer YOUR_API_KEY'
  ]);

  $visitors = curl_exec($ch);
  curl_close($ch);

  echo "Current visitors: $visitors";
  ?>
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  17
  ```
</CodeGroup>

### Polling for Updates

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

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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);
  ```

  ```python Python theme={null}
  import requests
  import time

  def get_current_visitors():
      response = requests.get(
          'https://plausible.io/api/v1/stats/realtime/visitors',
          params={'site_id': 'example.com'},
          headers={'Authorization': 'Bearer YOUR_API_KEY'}
      )
      return response.json()

  # Poll every 30 seconds
  while True:
      visitors = get_current_visitors()
      print(f'Current visitors: {visitors}')
      time.sleep(30)
  ```
</CodeGroup>

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

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

### Common Errors

**401 Unauthorized** - Invalid or missing API key

```json theme={null}
{
  "error": "Invalid API key"
}
```

**400 Bad Request** - Missing site\_id parameter

```json theme={null}
{
  "error": "Missing site_id parameter"
}
```

**404 Not Found** - Site not found

```json theme={null}
{
  "error": "Site not found"
}
```