Events API reference

With Swetrix you can programmatically record page views or custom events manually. Typically this API is used when doing server-side tracking or in mobile/native applications.

We already provide several integrations and a script for this, but if for some reason none of these options work for you, you can use the Events API instead.

Concepts

Unique visitors tracking

The API relies on the client's IP address and user agent to create a temporary session (a salted hash that is permanently removed from our database 30 minutes after the last interaction or at 12:00 AM UTC, whichever comes first). We never store any visitor identifiable information in our database.

Request headers

User-Agent

This header is used to determine the visitor's browser, operating system and device type. It's also used to determine whether or not the visitor is a bot. We also use this header to create a temporary session for the visitor.

X-Forwarded-For

Used to explicitly set the IP address of the visitor. If not set, the remote IP of the sender is used automatically. Depending on your use-case:

1. If sending the event directly from your visitor's device, this header does not need to be set.
2. If sending the event from a backend server or a proxy, make sure to set this header to the visitor's real IP address.

The IP address is never stored in raw form — it's used to calculate the temporary visitor session described above and to fill the geolocation reports (country, region, city).

If the header contains a comma-separated list (as it does when the request passed through a chain of proxies), the first valid IP address from the list is used. Both IPv4 and IPv6 addresses are supported. More information about the header format can be found on MDN.

X-Client-IP-Address (legacy)

Older Swetrix integrations used the custom X-Client-IP-Address header for the same purpose. It's still honoured and takes precedence over X-Forwarded-For, so existing setups keep working — but it's not recommended for new integrations; use the standard X-Forwarded-For header instead.

Content-Type

Must be set to application/json for all requests.

Pageview event structure

Pageview payload

Performance metrics payload

This section describes the structure of the perf object which is used to record performance metrics related to the page loading.

All of the values are numbers in milliseconds.

Custom event structure

Error event structure

Heartbeat event structure

Identify event structure

Revenue event structure

Endpoints

POST /log

This endpoint records pageview events.

curl -i -X POST https://api.swetrix.com/log \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/116.0" \
  -H "X-Forwarded-For: 192.0.2.1" \
  -H "Content-Type: application/json" \
  -d '{"pid":"YOUR_PROJECT_ID","lc":"en-US","pg":"/"}'

{}

POST /log/custom

This endpoint records custom events.

curl -i -X POST https://api.swetrix.com/log/custom \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/116.0" \
  -H "X-Forwarded-For: 192.0.2.1" \
  -H "Content-Type: application/json" \
  -d '{"pid":"YOUR_PROJECT_ID","lc":"en-US","pg":"/"}'

{}

POST /log/hb

This endpoint is used for heartbeat events. Heartbeat events are used to determine if the user session is still active. This allows you to see the 'Live Visitors' counter in the Dashboard panel. It's recommended to send heartbeat events every 30 seconds. We also extend the session lifetime after receiving a pageview or custom event.

curl -i -X POST https://api.swetrix.com/log/hb \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/116.0" \
  -H "X-Forwarded-For: 192.0.2.1" \
  -H "Content-Type: application/json" \
  -d '{"pid":"YOUR_PROJECT_ID"}'

WebSocket Heartbeat

For more efficient heartbeat tracking (like long-running sessions, desktop applications, etc.), you can use the WebSocket interface as an alternative to the HTTP endpoint.

Connection Details:

• URL: https://api.swetrix.com
• Namespace: /hb
• Query Parameters:
  • pid (Required): Your Project ID.

Events:

• connected: Emitted by the server when the session is successfully established.
• error: Emitted if the connection is rejected (e.g., missing PID, invalid origin, or bot detected).

Example (using socket.io-client):

import { io } from "socket.io-client";

const socket = io("https://api.swetrix.com/hb", {
  query: {
    pid: "YOUR_PROJECT_ID",
  },
  transports: ["websocket"], // Optional: force WebSocket transport
});

socket.on("connected", () => {
  console.log("Heartbeat session established");
});

socket.on("error", (err) => {
  console.error("Heartbeat error:", err.message);
});

// The server automatically handles the heartbeat interval (every 60s)
// Keep the connection open as long as the user is active on the page

{}

POST /log/identify

This endpoint identifies the visitor with your own user ID (e.g. after they log in). It links the visitor's current anonymous profile — derived from the request's IP address and User-Agent — to the identified profile derived from the supplied profileId, so the activity recorded before identification is attributed to the identified profile in the dashboard.

After calling it, keep sending the same profileId field with your pageview / custom event payloads so subsequent events are stamped with the identified profile directly. The tracking script does both automatically via swetrix.identify().

Notes:

• An anonymous profile is linked to the first identified profile that claims it — repeated calls with the same profileId are idempotent, and calls with a different profileId won't re-link the anonymous history (but are otherwise harmless).
• Since anonymous profiles rotate monthly, the linking covers the visitor's recent anonymous activity — up to about a month back on that device and network.
• Values like null, undefined, guest or an empty string are rejected with a 400 error, as they would fuse unrelated visitors into a single profile.
• The optional traits object is stored against the identified profile and displayed on its dashboard page. Traits are merged per key, so a later call only overwrites the keys it carries and an empty / null value removes one.

curl -i -X POST https://api.swetrix.com/log/identify \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/116.0" \
  -H "X-Client-IP-Address: 192.0.2.1" \
  -H "Content-Type: application/json" \
  -d '{"pid":"YOUR_PROJECT_ID","profileId":"user-12345","traits":{"email":"john@example.com","plan":"premium"}}'

{ "profileId": "usr_user-12345" }

The returned profileId is the identified profile ID your events are stored under — the same value you'd use for revenue attribution.

POST /log/error

This endpoint records error events. These error events are later aggregated in the dashboard under the Errors tab.

curl -i -X POST https://api.swetrix.com/log/error \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/116.0" \
  -H "X-Forwarded-For: 192.0.2.1" \
  -H "Content-Type: application/json" \
  -d '{"pid":"YOUR_PROJECT_ID","lc":"en-US","pg":"/","name":"ParseError","message":"Malformed input","lineno":12,"colno":510,"filename":"https://example.com/assets/convert.js"}'

{}

POST /log/revenue

This endpoint records revenue transactions (sales, subscription charges, and refunds). Use it when you sell through a platform that isn't Stripe or Paddle (Shopify, JTL Shop, Lemon Squeezy, in-app purchases, custom checkouts, etc.). For Stripe and Paddle, prefer the built-in integrations under Project Settings > Revenue instead — they sync automatically every 30 minutes.

The first call against a project automatically enables API revenue tracking and locks in the currency you sent as the project's reporting currency. You can change it later from Project Settings > Revenue.

curl -i -X POST https://api.swetrix.com/log/revenue \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pid":"YOUR_PROJECT_ID","transactionId":"order_42891","type":"sale","amount":49.99,"currency":"EUR","productName":"Pro plan (yearly)","profileId":"user-12345"}'

{
  "success": true,
  "transactionId": "order_42891"
}

Returns 409 Conflict if a Stripe or Paddle key is already connected for this project — disconnect it from Project Settings first to avoid double-counting.

See the Revenue Tracking guide for full setup walkthroughs (cURL, PHP / JTL Shop, Node.js), idempotency rules, and user attribution.

Status and error codes

201 Created

The request was successful and the event was recorded.

400 Bad Request

This error is usually returned when the request body is malformed (for example, the pid parameter is missing) or the project is disabled.

402 Payment Required

This error is usually returned when the project is not active (i.e. the subscription has expired or the quota has been exceeded). Please go to the Plan and billing page to check the current status and usage of your subscription.

403 Forbidden

This error is usually returned when the unique parameter is set to true and the event is not unique, i.e. the pageview event has already been recorded for this session. For POST /log/revenue it indicates that your API key does not have permission to manage the target project.

409 Conflict

Returned by POST /log/revenue when a Stripe or Paddle key is already connected for the project. Disconnect the existing source from Project Settings > Revenue before sending revenue via the API, otherwise transactions would be double-counted.

500 Internal Server Error

This error is usually returned when the server is unable to process the request due to a temporary problem (for example, the database is unavailable). If you receive this error, please try again later. If the problem persists, please contact us.

API wrappers

NodeJS

Currently we provide an official NodeJS API wrapper for the events API. You can find how to install and use it by opening its npm package page.

Contributing

We welcome any countributions to Swetrix. If you want to create your own API wrapper, feel free to do so. Please contact us and we will list your library here.

Also as an example, feel free to check out the source code of our NodeJS API wrapper.

Common request examples

Recording a pageview event using JavaScript fetch API

fetch("https://api.swetrix.com/log", {
  method: "POST",
  headers: {
    "User-Agent": "FORWARD_CLIENT_USER_AGENT_HERE",
    "X-Forwarded-For": "FORWARD_CLIENT_IP_ADDRESS_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    pid: "YOUR_PROJECT_ID",
    lc: "en-US",
    pg: "/",
    tz: "UTC",
    unique: false,
  }),
});

Recording a custom event using Go net/http

package main

import (
  "bytes"
  "encoding/json"
  "net/http"
)

func main() {
  payload, err := json.Marshal(map[string]interface{}{
    "pid": "YOUR_PROJECT_ID",
    "ev": "YOUR_EVENT_NAME",
    "unique": false,
  })
  if err != nil {
    panic(err)
  }

  req, err := http.NewRequest("POST", "https://api.swetrix.com/log/custom", bytes.NewBuffer(payload))
  if err != nil {
    panic(err)
  }

  req.Header.Set("User-Agent", "FORWARD_CLIENT_USER_AGENT_HERE")
  req.Header.Set("X-Forwarded-For", "FORWARD_CLIENT_IP_ADDRESS_HERE")
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
}

Recording a heartbeat event using PHP cURL

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.swetrix.com/log/hb');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'pid' => 'YOUR_PROJECT_ID',
]));

$headers = [
  'User-Agent: FORWARD_CLIENT_USER_AGENT_HERE',
  'X-Forwarded-For: FORWARD_CLIENT_IP_ADDRESS_HERE',
  'Content-Type: application/json',
];

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

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

Help us improve Swetrix

Was this page helpful to you?

YesNo

Learn how to contribute•Report a problem with this content