Track Events API

POST /api/track is the ingestion endpoint every event flows through — the browser tracking script uses it, and you can call it directly from a server to send events yourself. The body is a single JSON event, and the endpoint returns 204 No Content: the event is validated and queued, then written asynchronously.

POST https://dash.tinyanalytics.io/api/track

The event shape

Every event carries a type and the page context tinyanalytics can’t derive on its own. The server always derives identity, geo, channel, and device itself — it never trusts the client for those — so you send page context only. Send a pageview:

curl -X POST https://dash.tinyanalytics.io/api/track \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pageview",
    "siteId": 1,
    "pathname": "/pricing",
    "hostname": "example.com",
    "referrer": "https://google.com",
    "pageTitle": "Pricing"
  }'

await fetch("https://dash.tinyanalytics.io/api/track", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    type: "pageview",
    siteId: 1,
    pathname: "/pricing",
    hostname: "example.com",
    referrer: "https://google.com",
    pageTitle: "Pricing",
  }),
})

import requests

requests.post(
    "https://dash.tinyanalytics.io/api/track",
    json={
        "type": "pageview",
        "siteId": 1,
        "pathname": "/pricing",
        "hostname": "example.com",
        "referrer": "https://google.com",
        "pageTitle": "Pricing",
    },
)

Send a custom event with properties:

curl -X POST https://dash.tinyanalytics.io/api/track \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom_event",
    "siteId": 1,
    "pathname": "/checkout",
    "eventName": "purchase",
    "props": { "plan": "pro", "seats": 5 },
    "revenue": 49.0,
    "currency": "USD"
  }'

await fetch("https://dash.tinyanalytics.io/api/track", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    type: "custom_event",
    siteId: 1,
    pathname: "/checkout",
    eventName: "purchase",
    props: { plan: "pro", seats: 5 },
    revenue: 49.0,
    currency: "USD",
  }),
})

import requests

requests.post(
    "https://dash.tinyanalytics.io/api/track",
    json={
        "type": "custom_event",
        "siteId": 1,
        "pathname": "/checkout",
        "eventName": "purchase",
        "props": {"plan": "pro", "seats": 5},
        "revenue": 49.0,
        "currency": "USD",
    },
)

Fields

Every event includes these base fields:

string

required

The event type. Valid values are listed below.

number

required

Your numeric site ID.

string

required

The page path, up to 2048 characters.

string

Up to 253 characters.

string

Up to 2048 characters.

string

Up to 2048 characters.

string

Up to 512 characters.

string

Up to 35 characters.

number

Viewport width in pixels, 0–65535.

number

Viewport height in pixels, 0–65535.

string

A stable ID set via identify.

A custom_event (and an error) adds:

string

required

Up to 256 characters — the grouping key in your Events reports.

object

Free-form JSON, up to 8 KB serialized.

number | string

A revenue amount in major currency units (e.g. 49.0 = $49.00). See Revenue analytics.

string

A 3-letter currency code, e.g. USD.

Valid type values are pageview, custom_event, error, performance, engagement, and the auto-captured interactions (outbound, file_download, button_click, copy, form_submit, input_change). The browser tracker emits most of these for you — from a server you’ll typically send pageview and custom_event. Unknown fields are rejected with a 400.

Sending events from a server

When you call /api/track from your backend, add an API key so the event is attributed to the visitor, not your server:

curl -X POST https://dash.tinyanalytics.io/api/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom_event",
    "siteId": 1,
    "pathname": "/api/webhook",
    "eventName": "subscription_renewed",
    "ipAddress": "203.0.113.10",
    "userAgent": "Mozilla/5.0 (Macintosh; …)"
  }'

With a valid key, tinyanalytics honors the ipAddress and userAgent you supply so geo, device, and cookieless identity reflect the real visitor — without them, every server-sent event would collapse to your server’s own IP. These override fields are ignored on a request without a valid key. Server-side ingestion is subject to a per-key rate limit.

Identify API

Attach a stable user ID to these events.

API keys

Create the key server-side ingestion needs.

Rate limits & CORS

The ingestion rate limit and origin rules.

Track custom events

The browser way to send the same events.

Start here

Core API

Authentication & tools

Endpoint reference

The event shape

Fields

Sending events from a server

Identify API

API keys

Rate limits & CORS

Track custom events

​The event shape

​Fields

​Sending events from a server

​Related

Identify API

API keys

Rate limits & CORS

Track custom events

The event shape

Fields

Sending events from a server

Related