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

caution

For the unique (and live) visitor functionality to work properly, each request must have the User-Agent and X-Client-IP-Address HTTP headers set. If you don't set these headers, the API will still work, but the unique visitor count will be incorrect.

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-Client-IP-Address

This header is used to determine the visitor's IP address. You must pass the visitor's IP address using this header, otherwise the API will use the IP address of the server making the request (i.e. your server's IP address), resulting in incorrect unique and live visitor data.

Content-Type

Must be set to application/json for all requests.

Pageview event structure

Pageview payload

Name	Type	Required	Description
`pid`	`string`	`true`	A project ID to record the pageview event for
`tz`	`string`	`false`	Visitor's timezone (used as a backup in case IP geolocation fails). I.e. if it's set to `Europe/Kiev` and IP geolocation fails, we will set the country of this entry to `Ukraine`)
`pg`	`string`	`false`	A page to record the pageview event for (e.g. `/home`). All our scripts send the `pg` string with a slash (`/`) at the beginning, it's not a requirement but it's best to do the same so the data would be consistent when used together with our official scripts
`lc`	`string`	`false`	A locale of the user (e.g. `en-US` or `uk-UA`)
`ref`	`string`	`false`	A referrer URL (e.g. `https://example.com/`)
`so`	`string`	`false`	A source of the pageview (e.g. `ref`, `source` or `utm_source` GET parameter)
`me`	`string`	`false`	A medium of the pageview (e.g. `utm_medium` GET parameter)
`ca`	`string`	`false`	A campaign of the pageview (e.g. `utm_campaign` GET parameter)
`unique`	`boolean`	`false`	If set to true, only unique visits will be saved
`perf`	`object`	`false`	An object with performance metrics related to the page load. See Performance metrics for more details

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.

Name	Type	Required	Description
`dns`	`number`	`false`	DNS Resolution time
`tls`	`number`	`false`	TLS handshake time
`conn`	`number`	`false`	Connection time
`response`	`number`	`false`	Response Time (Download)
`render`	`number`	`false`	Browser rendering the HTML page time
`dom_load`	`number`	`false`	DOM loading timing
`page_load`	`number`	`false`	Page load timing
`ttfb`	`number`	`false`	Time to first byte

Custom event structure

Name	Type	Required	Description
`pid`	`string`	`true`	A project ID to record the pageview event for
`ev`	`string`	`true`	An event identifier you want to track. This has to be a string, which: 1. Contains only English letters (a-Z A-Z), numbers (0-9), underscores (_) and dots (.). 2. Is fewer than 64 characters. 3. Starts with an English letter.
`unique`	`boolean`	`false`	If set to true, only 1 custom event will be saved per session
`pg`	`string`	`false`	A page that user sent data from (e.g. `/home`)
`lc`	`string`	`false`	A locale of the user (e.g. `en-US` or `uk-UA`)
`ref`	`string`	`false`	A referrer URL (e.g. `https://example.com/`)
`so`	`string`	`false`	A source of the pageview (e.g. `ref`, `source` or `utm_source` GET parameter)
`me`	`string`	`false`	A medium of the pageview (e.g. `utm_medium` GET parameter)
`ca`	`string`	`false`	A campaign of the pageview (e.g. `utm_campaign` GET parameter)
`meta`	`object`	`false`	A `key` / `value` pair of custom properties for your event (e.g. if your event is `signup`, you can include `meta` like `{ affiliate: 'Yes', currency: 'GBP' }`). The values of the object must be strings, the maximum number of keys allowed is 100 and the total length of the keys and values combined must be less than 2000 characters.

Error event structure

Name	Type	Required	Description
`pid`	`string`	`true`	A project ID to record the pageview event for
`name`	`string`	`true`	Error name (e.g. `ParseError`); Max length is 200
`message`	`string`	`false`	Error message (e.g. `Malformed input`); Max length is 2000
`lineno`	`number`	`false`	Line number
`colno`	`number`	`false`	Column number
`filename`	`number`	`false`	Error message (e.g. `https://example.com/assets/convert.js`); Max length is 1000
`tz`	`string`	`false`	Visitor's timezone (used as a backup in case IP geolocation fails). I.e. if it's set to `Europe/Kiev` and IP geolocation fails, we will set the country of this entry to `Ukraine`)
`pg`	`string`	`false`	A page that user sent data from (e.g. `/home`)
`lc`	`string`	`false`	A locale of the user (e.g. `en-US` or `uk-UA`)

Heartbeat event structure

Name	Type	Required	Description
`pid`	`string`	`true`	A project ID to record the heartbeat event for

Endpoints

POST /log

This endpoint records pageview events.

Request
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-Client-IP-Address: 192.0.2.1" \
  -H "Content-Type: application/json" \
  -d '{"pid":"YOUR_PROJECT_ID","lc":"en-US","pg":"/"}'

Response (201 Created)

{}

POST /log/custom

This endpoint records custom events.

Request
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-Client-IP-Address: 192.0.2.1" \
  -H "Content-Type: application/json" \
  -d '{"pid":"YOUR_PROJECT_ID","lc":"en-US","pg":"/"}'

Response (201 Created)

{}

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.

Request
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-Client-IP-Address: 192.0.2.1" \
  -H "Content-Type: application/json" \
  -d '{"pid":"YOUR_PROJECT_ID"}'

Response (201 Created)

{}

POST /log/error

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

Request
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-Client-IP-Address: 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"}'

Response (201 Created)

{}

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 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.

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-Client-IP-Address': '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-Client-IP-Address", "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-Client-IP-Address: FORWARD_CLIENT_IP_ADDRESS_HERE',
  'Content-Type: application/json',
];

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

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

Concepts​

Unique visitors tracking​

Request headers​

User-Agent​

X-Client-IP-Address​

Content-Type​

Pageview event structure​

Pageview payload​

Performance metrics payload​

Custom event structure​

Error event structure​

Heartbeat event structure​

Endpoints​

POST /log​

POST /log/custom​

POST /log/hb​

POST /log/error​

Status and error codes​

201 Created​

400 Bad Request​

402 Payment Required​

403 Forbidden​

500 Internal Server Error​

API wrappers​

NodeJS​

Contributing​

Common request examples​

Recording a pageview event using JavaScript fetch API​

Recording a custom event using Go net/http​

Recording a heartbeat event using PHP cURL​

Concepts

Unique visitors tracking

Request headers

User-Agent

X-Client-IP-Address

Content-Type

Pageview event structure

Pageview payload

Performance metrics payload

Custom event structure

Error event structure

Heartbeat event structure

Endpoints

POST /log

POST /log/custom

POST /log/hb

POST /log/error

Status and error codes

201 Created

400 Bad Request

402 Payment Required

403 Forbidden

500 Internal Server Error

API wrappers

NodeJS

Contributing

Common request examples

Recording a pageview event using JavaScript fetch API

Recording a custom event using Go net/http

Recording a heartbeat event using PHP cURL