Realtime Endpoints

The Realtime API provides access to currently active visitors on your website. Use these endpoints to display live visitor counts or build real-time monitoring dashboards.

Info

Realtime data covers visitors who have been active within the last 90 seconds. A visitor is considered active if they have sent at least one event (pageview, heartbeat, or goal) in that window.

Endpoints

GET /api/v1/realtime

Returns the number of visitors currently active on your website. This is a lightweight endpoint suitable for frequent polling. Only the site_id parameter is required — no date range parameters are needed.

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID (e.g., `ds_abc123`)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/realtime?site_id=ds_abc123"

{
  "results": {
    "visitors": 42
  },
  "meta": {
    "site_id": "ds_abc123",
    "window_seconds": 90
  }
}

GET /api/v1/realtime/visitors

Returns detailed information about each currently active visitor, including their location, device, current page, and identity data if available. Only the site_id parameter is required.

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID (e.g., `ds_abc123`)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/realtime/visitors?site_id=ds_abc123"

{
  "results": [
    {
      "visitor_id": "v_8f3a2b1c",
      "country": "United States",
      "city": "San Francisco",
      "browser": "Chrome",
      "os": "macOS",
      "device_type": "desktop",
      "referrer": "google.com",
      "pathname": "/pricing",
      "session_duration": 245,
      "total_visits": 18,
      "user_id": "usr_12345",
      "display_name": "Jane Doe",
      "email": "jane@example.com"
    },
    {
      "visitor_id": "v_2e5f8a9b",
      "country": "United Kingdom",
      "city": "London",
      "browser": "Safari",
      "os": "iOS",
      "device_type": "mobile",
      "referrer": "twitter.com",
      "pathname": "/blog/getting-started",
      "session_duration": 32,
      "total_visits": 1,
      "user_id": null,
      "display_name": null,
      "email": null
    }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "window_seconds": 90,
    "total_active": 2
  }
}

Tip

For real-time dashboards, poll the /api/v1/realtime endpoint every 10–15 seconds for the visitor count, and use /api/v1/realtime/visitorsless frequently (every 30–60 seconds) to reduce API usage.

Goals & Revenue

Funnels