Realtime Visitors API

The realtime API endpoint calculates the current number of visitors by counting unique visitors who have triggered pageview events in the last 3 minutes. This matches the polling interval used by the HeaderList component in the dashboard.

How It Works

The endpoint authenticates each request using your website's API token, which you can generate here. Each website has its own unique API token for security.

Use Case

Your pricing card can have a discounted price for the next (for example, 15) customers. You can show the current visitors on that component to display urgency to the user to convert.

Endpoint

GET https://versatailor.com/api/v1/realtime

Authentication

This endpoint requires authentication using a Bearer token.

Authorization: Bearer vt_your_api_token_here

Query Parameters

Parameter	Type	Required	Description
websiteId	string	Yes	The unique identifier of your website

Response Format

On success, the API returns a JSON object with the following structure:

{
  "currentVisitors": number,
  "websiteId": string,
  "timestamp": string
}

Response Fields

• currentVisitors: The number of currently active visitors on your website
• websiteId: The ID of the website the data pertains to
• timestamp: The time when the data was collected (in ISO 8601 format)

Error Responses

The API may return the following error responses:

401 Unauthorized

Missing or invalid authorization header. Expected: Bearer

400 Bad Request

websiteId is required

404 Not Found

Website not found

Example Usage

cURL Request

curl "https://versatailor.com/api/v1/realtime?websiteId=your_website_id" \
  -H "Authorization: Bearer vt_your_api_token_here"

JavaScript Fetch

fetch("https://versatailor.com/api/v1/realtime?websiteId=your_website_id", {
  headers: {
    Authorization: "Bearer vt_your_api_token_here",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Successful Response

{
  "currentVisitors": 5,
  "websiteId": "your_website_id",
  "timestamp": "2025-07-30T17:09:37.000Z"
}

Integration Examples

React Component

import { useState, useEffect } from "react";

function VisitorCounter() {
  const [visitors, setVisitors] = useState(0);

  useEffect(() => {
    const fetchVisitors = async () => {
      try {
        const response = await fetch(
          `https://versatailor.com/api/v1/realtime?websiteId=${process.env.NEXT_PUBLIC_WEBSITE_ID}`,
          {
            headers: {
              Authorization: `Bearer ${process.env.NEXT_PUBLIC_API_KEY}`,
            },
          }
        );
        const data = await response.json();
        setVisitors(data.currentVisitors);
      } catch (error) {
        console.error("Failed to fetch visitor count:", error);
      }
    };

    fetchVisitors();
    const interval = setInterval(fetchVisitors, 60000); // Update every minute

    return () => clearInterval(interval);
  }, []);

  return (
    <div className="visitor-counter">
      <span className="count">{visitors}</span> people viewing this page
    </div>
  );
}

Node.js Server

async function getCurrentVisitors(websiteId, apiKey) {
  try {
    const response = await fetch(
      `https://versatailor.com/api/v1/realtime?websiteId=${websiteId}`,
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json",
        },
      }
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    return data.currentVisitors;
  } catch (error) {
    console.error("Error fetching visitor count:", error);
    return null;
  }
}

Best Practices

• Cache responses to avoid hitting rate limits
• Handle errors gracefully - don't let API failures break your user experience
• Use appropriate polling intervals - don't poll too frequently
• Implement fallbacks for when the API is unavailable

Rate Limits

• Free plans: 100 requests per hour
• Pro plans: 1,000 requests per hour
• Enterprise plans: 10,000 requests per hour

Next Steps

• Get your API key
• Learn about custom event tracking
• Explore server-side tracking