Getting Started#
Antics is not only a pageview count.
No collection cookie. The tracker does not set or read one.
The visitor salt for the current UTC day is stored beside the data directory and loaded again after a restart. It is discarded at UTC midnight, so yesterday’s bucket cannot be remade. Event rows stay until retention.
A path-scoped site can sit on the same host as the host site.
Short links are included, with their own allowance.
The attention figure is not the raw time on the page.
Add analytics to your website in three steps: register the host, add the snippet, open the dashboard.
The public first-run page is antics.turtletech.us/docs/start (also /install). Managed accounts are invite-only: request access, then complete the same path once signed in.
1. Register your host#
Request access, sign in, and create a site from the Antics dashboard. A host registration such as example.com receives tokenless traffic for that host, including child paths.
Subdomains are separate hosts: register docs.example.com or lab.example.com as their own site when the subdomain has separate ownership or reporting needs.
GitHub Pages crate sites use the same host-only path: register leidarljos.github.io and keep the tokenless snippet. Child paths such as /ljos/ report to that host without a data-token.
For hosted project docs and other path-scoped pages that need their own dashboard, also register the exact path prefix, for example:
lode-org.github.io/readcon-core
2. Add the tracker#
For a host site, add the tokenless snippet:
<script defer src="https://antics-api.turtletech.us/antics.js"></script>
For a path-scoped site, copy the token-bound snippet from Settings:
<script defer src="https://antics-api.turtletech.us/antics.js" data-token="YOUR_TRACKER_TOKEN"></script>
The token routes traffic into the path site. Antics still verifies the browser origin and registered path, so a token for example.com/docs cannot report traffic for example.com/blog.
Tokenless traffic on the same host continues to report to the host site, so an organization can keep example.com aggregate stats while example.com/project-a and example.com/project-b have stakeholder-specific dashboards.
3. View your dashboard#
Visit antics.turtletech.us/dashboard to see your analytics. Data appears within 60 seconds of the first visit.
Try it locally in five minutes#
This path stays on your machine. Leave VALKEY_URL and any dashboard or billing URL unset, so sessions stay in memory and startup does not dial another service.
export ANTICS_DATA_DIR="$HOME/antics-data"
export LISTEN_ADDR="127.0.0.1:8480"
export ANTICS_LINK_BASE_URL="http://127.0.0.1:8480"
export ANTICS_BOOTSTRAP_API_KEY="choose-a-local-key-here"
mkdir -p "$ANTICS_DATA_DIR"
antics
antics --help prints the variables and exits. The default listen address is 0.0.0.0:8480. ANTICS_DATA_DIR must be a directory the process can write; /var/lib/antics is the default and is often not writable. The bootstrap key is stored as a hash and is not written to the log. The key is installed only when ANTICS_MODE is not managed and the control store has no accounts yet. A key shorter than 16 characters stops startup only in that case. Managed mode and a store that already has an account leave the value unused, including a short one.
Register a host. The response is the site, including id and tracker_token:
curl -sS -X POST "http://127.0.0.1:8480/api/sites" \
-H "Authorization: Bearer $ANTICS_BOOTSTRAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"example.com"}'
Send the first pageview the way the tracker does. Origin must be that host. 202 means the collector accepted it:
curl -sS -D - -o /dev/null -X POST "http://127.0.0.1:8480/api/event" \
-H "Origin: https://example.com" \
-H "Content-Type: text/plain" \
-d '{"u":"https://example.com/hello"}'
Read today’s stats. summary.total_pageviews is 1 after the collector flushes, within a few seconds. _leave, _dwell, _vitals, and _outbound are not extra pageviews.
curl -sS "http://127.0.0.1:8480/api/stats/SITE_ID?period=today" \
-H "Authorization: Bearer $ANTICS_BOOTSTRAP_API_KEY"
A path-scoped site is a second registration, for example example.com/docs. Its snippet sets data-token to that site’s tracker_token. Tokenless traffic on the same host stays on the host site, and _vitals carries the token so the path site keeps its own web-vitals rows. Stats for the path site use that site’s id.
Create a short link, then follow it on the local server. The follow response is 302 with Location set to the target:
curl -sS -X POST "http://127.0.0.1:8480/api/links" \
-H "Authorization: Bearer $ANTICS_BOOTSTRAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"target_url":"https://example.com/hello"}'
curl -sS -D - -o /dev/null "http://127.0.0.1:8480/r/SLUG"
A refused registration or export is JSON with error and message, not an empty status. A duplicate host is 409. A domain with a port, no dot, or a user name is 400 and the message says what to send instead.
Days, alerts, changepoints, and exports use the site timezone (IANA name, default UTC). Storage stays UTC; the query boundary folds hourly rollups onto local days. Retention still prunes on UTC day boundaries, so the prune edge can move by up to a day relative to local time.
Managed Plans and Quotas#
Antics quotas are separate from every other TurtleTech app. Ridley, OokCite, Babbler, and TurtleTech Data subscriptions do not contribute to an Antics allowance.
Plan |
Pageviews per month |
Pageviews kept |
Stats kept |
|---|---|---|---|
Free |
1,000,000 pooled |
90 days |
25 months |
Pro |
5,000,000 pooled |
90 days |
25 months |
Team |
25,000,000 pooled |
90 days |
25 months |
Raw events are kept for 90 days. Aggregated statistics are kept for 25 months.
Sites share the account pageview pool. Registration stops at 200 hosts per account so empty-host spam cannot grow without bound. The managed collector applies a soft allowance before its hard ingestion cap. The dashboard reports usage against the advertised monthly allowance. Storage is billed at TurtleTech storage rates.
Native Links uses a separate allowance for each source application. These are the Antics dashboard allowances:
Plan |
Active links |
Redirects per month |
|---|---|---|
Free |
100 |
10,000 |
Pro |
5,000 |
500,000 |
Team |
50,000 |
5,000,000 |
Redirect traffic remains available when monthly usage reaches the advertised allowance. The allowance is metered for reporting and plan review rather than used to break an established public URL. See Create and manage short links for lifecycle and API behavior.
Framework Integration#
Hugo#
# config.toml
[params.antics]
host = "https://antics-api.turtletech.us"
If your theme supports the extra-head.html partial:
<!-- layouts/partials/extra-head.html -->
<script defer src="https://antics-api.turtletech.us/antics.js"></script>
Jekyll#
<!-- _includes/head.html -->
<script defer src="https://antics-api.turtletech.us/antics.js"></script>
SvelteKit#
<!-- src/app.html, before %sveltekit.head% -->
<script defer src="https://antics-api.turtletech.us/antics.js"></script>
Next.js / Astro / any HTML#
<!-- In your <head> -->
<script defer src="https://antics-api.turtletech.us/antics.js"></script>
Custom Events#
Track user actions from JavaScript:
antics.event('signup', { plan: 'pro' });
antics.event('download', { file: 'report.pdf' });
On the managed service a free plan rejects these named events with 429 and custom_events_require_a_paid_plan. A suspended account is 429 and account_suspended. A full pageview allowance is 429 and pageview_allowance_full, including tracker beacons. Too many events from one address is 429, rate_limited, and Retry-After. A usage meter that cannot be read is 503 and meter_unavailable. A full collector queue is 503 and collector_busy. Pro and Team accept custom events. _leave, _dwell, _vitals, and _outbound are tracker beacons, not custom events, and they do not add a pageview. CSV export is also a paid-plan feature: a free account receives 402 and JSON that names csv_export_requires_a_paid_plan.
What Gets Tracked#
Pageviews and same-day visitor buckets (daily pseudonymous identifier, no collection cookies)
Referrer domains and UTM parameters
Country (the source IP is used for GeoIP and visitor-bucket derivation; analytics events do not store the raw IP address)
Browser, OS, device type
Scroll depth and time on page
Core Web Vitals (LCP, INP, CLS)
Custom events with properties
SPA navigation (pushState/replaceState)