Realtime Visitors API

The realtime API endpoint gets you how many visitors are currently on your website. It is the same number displayed in your analytics dashboard in the "Visitors now" section

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 so they would convert.

Endpoint

GET https://trackfox.app/api/v1/realtime

Authentication

This endpoint requires authentication using a Bearer token.

Authorization: Bearer tf_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://trackfox.app/api/v1/realtime?websiteId=your_website_id" \
  -H "Authorization: Bearer tf_your_api_token_here"

JavaScript Fetch

fetch("https://trackfox.app/api/v1/realtime?websiteId=your_website_id", {
  headers: {
    Authorization: "Bearer tf_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://trackfox.app/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://trackfox.app/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;
  }
}

Next Steps

• Learn about custom event tracking
• Explore server-side tracking