Ingest API reference
Endpoint: POST {your-antlytics-origin}/api/ingest/pageview
Accepts JSON. All fields except tracking_id and pathname are optional.
| Field | Type | Description |
|---|---|---|
tracking_id | UUID (required) | Your site's tracking ID from the dashboard |
pathname | string (required) | URL path only, e.g. /blog/my-post (no query string) |
referrer | string | Full referrer URL |
session_id | UUID | Anonymous session id — use a sessionStorage UUID for consistency |
user_agent | string | User-Agent string (the server-side request header is preferred; use this only for non-browser SDK contexts) |
utm_source | string | Campaign source |
utm_medium | string | Campaign medium |
utm_campaign | string | Campaign name |
utm_term | string | Paid search keyword |
utm_content | string | Differentiates creatives or links |
Country and device type are always derived server-side from CDN-injected headers (X-Vercel-IP-Country) and the User-Agent request header. These values cannot be overridden from the request body, which ensures geography data cannot be forged by client scripts.
The dashboard snippet fills UTM fields from the current page URL automatically.
Rate limits
The ingest endpoint enforces sliding-window rate limits per IP address and per tracking ID. Requests that exceed the limit receive a 429 Too Many Requests response with a Retry-After header indicating when to retry.
Bot and spam filtering
The ingest endpoint applies a lightweight baseline filter before writing to the database. Requests with User-Agent strings matching known bots, crawlers, and headless browsers are silently accepted (HTTP 200) but not recorded, so your dashboard reflects only real visitor traffic. A similar check runs on the referrer field to drop known spam referrer injection. The filter is applied server-side and cannot be bypassed from the client payload.