PricingDocsLog inSign up

Documentation

IntroductionQuick StartAuthenticationProjectsAnalyticsLive ViewsCustom EventsBypassing Ad Blockers

Introduction

The Pulse REST API lets you access your analytics data, manage projects, and stream live visitor counts programmatically. All API endpoints are available to Pro subscribers using an API key.

Base URL

https://api.pulse.velovix.com

Quick Start

Add Pulse to any website by pasting a single script tag into your <head>. No build step, no configuration.

<script
  src="https://api.pulse.velovix.com/viewsTracker.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>

Replace YOUR_PROJECT_ID with the ID found on your project's dashboard page. Page views will appear within seconds.

What gets tracked?

Page URL, referrer, device type, browser, and country that's it. No cookies, no fingerprinting, no personal data.

Authentication

API requests are authenticated using an API key passed in the X-Api-Key header. API keys require a Pro subscription and can be created in your Account page.

curl https://api.pulse.velovix.com/api/v1/projects \
  -H "X-Api-Key: pulse_live_your_key_here"

Managing keys via API

GET/api/v1/user/apiKeysList your API keys
POST/api/v1/user/apiKeys?name=Create a new key
DELETE/api/v1/user/apiKeys?name=Revoke a key by name

Store your key securely

Your key is only shown once at creation time. Pulse stores a hashed copy and cannot recover it. If you lose it, delete the key and create a new one.

Projects

A project represents a single tracked domain. Each project gets its own ID used to scope analytics queries.

GET/api/v1/projects

Returns all projects belonging to the authenticated user.

Response

[
  {
    "id": "db5790a0-847c-40fa-b503-d343ba28f3c6",
    "name": "My Site",
    "domain": "example.com",
    "createdAt": "2025-01-15T10:00:00Z"
  }
]
GET/api/v1/projects/{id}

Returns a single project by its ID.

Parameters

idpath · requiredThe project UUID.

Response

{
  "id": "db5790a0-847c-40fa-b503-d343ba28f3c6",
  "name": "My Site",
  "domain": "example.com",
  "createdAt": "2025-01-15T10:00:00Z"
}
POST/api/v1/projects

Creates a new project. Free accounts are limited to 5 projects.

Parameters

namebody · requiredDisplay name for the project.
domainbody · requiredThe domain to track (e.g. example.com).

Response

project-created
DELETE/api/v1/projects/{id}

Permanently deletes a project and all its analytics data.

Parameters

idpath · requiredThe project UUID.

Response

200 OK

Analytics

Query aggregated analytics for any of your projects. Data is retained for 30 days on the Free plan and 2 years on Pro.

GET/api/v1/analytics/{id}

Returns aggregated analytics for a project over the given time range.

Parameters

idpath · requiredThe project UUID.
fromquery · optionalStart date (ISO 8601). Defaults to 30 days ago.
toquery · optionalEnd date (ISO 8601). Defaults to today.

Response

{
  "totalViews": 4821,
  "viewsPerDay": [
    { "date": "2025-04-01", "count": 142 }
  ],
  "topPages": [
    { "url": "/", "count": 1930 }
  ],
  "topReferrers": [
    { "referrer": "google.com", "count": 874 }
  ],
  "devices": [
    { "device": "desktop", "count": 3100 }
  ],
  "browsers": [
    { "browser": "Chrome", "count": 2500 }
  ],
  "countries": [
    { "country": "US", "count": 1800 }
  ]
}
GET/api/v1/analytics/{id}/export

Returns the same analytics payload as a downloadable CSV file.

Parameters

idpath · requiredThe project UUID.
fromquery · optionalStart date (ISO 8601).
toquery · optionalEnd date (ISO 8601).

Response

Content-Type: text/csv

date,views
2025-04-01,142
2025-04-02,198
...

Live Views

The live endpoint streams the current active visitor count for a project using Server-Sent Events (SSE). The connection stays open and pushes an update whenever the count changes.

GET/api/v1/analytics/{id}/live

Opens a persistent SSE stream that emits the live visitor count.

Parameters

idpath · requiredThe project UUID.

Response

data: 0
data: 1
...

Example — JavaScript

const es = new EventSource(
  "https://api.pulse.velovix.com/api/analytics/PROJECT_ID/live?api_key=pulse_live_your_key_here"
);
es.onmessage = (e) => {
  const liveVisitors = parseInt(e.data);
  console.log("Live visitors:", liveVisitors);
};

Pro only

Live visitor data is only available on the Pro plan. The endpoint returns 401 for Free accounts.

Custom Events

Custom events let you track specific actions on your site like signups, purchases, or button clicks. They are available to Pro subscribers and require the Pulse script to be installed.

Basic usage

Once the script is installed, call window.pulse.track() from anywhere on your site.

// simple event
pulse.track("signup");

// with custom properties
pulse.track("purchase", { plan: "pro" });

// 404 tracking
pulse.track("404", { path: window.location.pathname });

TypeScript support

For intellisense and type safety, paste this declaration file into your project:

// pulse.d.ts
interface PulseProps {
  [key: string]: string | number | boolean;
}
interface Pulse {
  track: (name: string, props?: PulseProps) => void;
}
declare global {
  interface Window {
    pulse: Pulse;
  }
}

Revenue tracking

Pass a revenue property to track monetary value associated with an event. Revenue is displayed separately in your dashboard.

pulse.track("purchase", { plan: "pro", revenue: 7.00 });
POST/api/v1/events

Records a custom event for a project. Called automatically by pulse.track() — you rarely need to call this directly.

Parameters

projectIdbody · requiredThe project UUID.
namebody · requiredEvent name (e.g. signup, purchase, 404).
urlbody · optionalPage URL where the event occurred.
visitorIdbody · optionalVisitor ID from localStorage.
revenuebody · optionalMonetary value associated with the event.
propsbody · optionalKey-value pairs of custom properties.

Response

200 OK

Pro only

Custom events are only available on the Pro plan. Calls from Free plan projects return 403.

Bypassing Ad Blockers

By default, the Pulse script is loaded from api.pulse.velovix.com which some ad blockers may block. To ensure accurate data, you can proxy the script through your own domain so it appears as a first-party request.

Next.js

Add the following to your next.config.js or next.config.ts:

async rewrites() {
  return [
    {
      source: '/pp/script.js',
      destination: 'https://api.pulse.velovix.com/viewsTracker.js',
    },
    {
      source: '/pp/track',
      destination: 'https://api.pulse.velovix.com/api/track',
    },
  ]
}

Then update your script tag to load from your own domain:

<script defer src="/pp/script.js" data-project-id="YOUR_PROJECT_ID"></script>

Nginx

Add the following to your Nginx server block:

location = /pp/script.js {
    proxy_pass https://api.pulse.velovix.com/viewsTracker.js;
    proxy_set_header Host api.pulse.velovix.com;
}

location = /pp/track {
    proxy_pass https://api.pulse.velovix.com/api/track;
    proxy_set_header Host api.pulse.velovix.com;
}

Then update your script tag to load from your own domain:

<script defer src="/pp/script.js" data-project-id="YOUR_PROJECT_ID"></script>

Caddy

Add the following to your Caddyfile:

handle /pp/script.js {
    reverse_proxy https://api.pulse.velovix.com/viewsTracker.js
}

handle /pp/track {
    reverse_proxy https://api.pulse.velovix.com/api/track
}

Then update your script tag to load from your own domain:

<script defer src="/pp/script.js" data-project-id="YOUR_PROJECT_ID"></script>