Server API

createAnalytik, its options and the object it returns, with the admin, privacy and geo options.

Exported from analytik/server. The server is a Hono app, so it runs anywhere that serves a fetch handler.

import { createAnalytik } from 'analytik/server'

createAnalytik(options)

function createAnalytik(options: CreateAnalytikOptions): Analytik

Options

Hooks

interface HookEvent {
  siteId: string
  type: 'pageview' | 'goal' | 'outbound' | 'revenue'
  name: string | null
  path: string
  props: Props | null
  ts: number
}
interface AnalytikHooks {
  beforeIngest?(event: HookEvent): HookEvent | null | void | Promise<HookEvent | null | void>
  onEvent?(event: HookEvent & { visitorId: string; sessionId: string }): void | Promise<void>
  onPayment?(payment: Payment): void | Promise<void>
}

beforeIngest runs before the write: null drops the event, a changed event (only name, path and props) is stored instead. onEvent and onPayment run after the write, through the platform’s waitUntil where there is one. Each hook has 1 second; a throw or timeout is logged and ignored. See the guide.

Admin

admin.password is the dashboard password and admin.secret signs the session cookie. createAnalytik() throws at startup when the password is empty or the secret is shorter than 32 characters; generate one with openssl rand -hex 32. To integrate with your own authentication, pass { verify } instead: it receives the Request and resolves to true to allow it.

createAnalytik({
  storage,
  admin: { verify: async (request) => request.headers.get('x-internal-user') !== null },
})

Allowed origins

allowedOrigins is matched against hostnames, not full origins, so write 'blog.example.com', not 'https://blog.example.com'.

• 'site-domains' (default): the page must be on the site’s domain or one of its subdomains. A site with allowLocalhost also accepts localhost.
• A list of hostnames: those hostnames and their subdomains are accepted in addition to the site’s own domain.
• 'any': the check is off.

Client IP and trustProxy

The server needs the visitor’s IP address for rate limits, the site’s ignored-IP list and the strict visitor hash. The address is used and then discarded, never stored. trustProxy decides which request headers may supply it, because a client can send any header it likes:

Without an IP, strict-mode visitor ids are built from the user agent and the site only, so all visitors with the same user agent collapse into one visitor. The per-client event limit is then skipped, and the attribution and login limits are shared by everyone. On a VPS behind Caddy or nginx, set trustProxy: 'forwarded'. If your proxy sets a different header, read it yourself:

createAnalytik({
  storage,
  admin,
  clientIp: (request) => request.headers.get('x-real-ip'),
})

The returned object

ingest

IngestInput has a payload (the untrusted tracker payload, unknown) and optional ip, userAgent, origin, geo and doNotTrack. The IP and user agent feed the strict-mode hash and the ignored-IP list and are never stored. The result is an IngestResult:

• { status: 202, visitorId, sessionId } when the event was accepted. Both ids are null and filtered is 'bot', 'ignored-ip' or 'paused' (tracking is paused for the site) when the event was dropped on purpose.
• { status: 400 | 403 | 404, error } when it was rejected.

const result = await analytik.ingest({
  payload: { w: 'SITE_ID', t: 'goal', u: 'https://example.com/pricing', n: 'signup' },
  ip: request.headers.get('x-real-ip'),
  userAgent: request.headers.get('user-agent'),
})
if (result.status !== 202) console.warn(result.error)

recordPayment

RecordPaymentInput is a PaymentInput plus a required siteId and an optional provider (default api). The result is { payment, duplicate }; duplicate is true when a payment with that id already exists and nothing changed.

const { payment, duplicate } = await analytik.recordPayment({
  siteId: 'SITE_ID',
  id: 'ord_8123',
  amount: 4900,
  currency: 'USD',
})

stats

const { stats } = analytik

const overview = await stats.overview('SITE_ID', {
  from: Date.UTC(2026, 9, 1),
  to: Date.UTC(2026, 10, 1),
  interval: 'day',
  tz: 'Europe/Bratislava',
  filters: { country: 'DE' },
})

The query argument is a Query and the result is an Overview; see Types. from is inclusive and to exclusive, both in Unix milliseconds. Unknown sites throw an AnalytikError with status 404.

stats.sessions, stats.events and stats.payments return a Page and take the list options of the HTTP API as a third argument:

const refunds = await stats.payments(
  'SITE_ID',
  { from: Date.UTC(2026, 9, 1), to: Date.UTC(2026, 10, 1) },
  { kind: 'refund', sort: 'amount', order: 'desc', offset: 0, limit: 25 },
)
console.log(refunds.total, refunds.items)

stats.properties(siteId, query, { name, key? }) returns the custom properties of one goal’s events as a PropertiesResult: its keys, or with key the values of that key (50 at most, the rest in other). Filter by a property with filters: { 'prop:plan': 'pro' } in any query.

stats.targets(siteId) takes no query: it returns the progress of the site’s goal targets in their own periods, as a TargetsResult.

stats.vitals(siteId, query) returns the 75th percentile of Core Web Vitals over the range as a VitalsResult.

stats.journeys(siteId, query) returns the paths sessions take after the first page as a JourneysResult.

stats.retention(siteId, query) returns weekly cohorts of new visitors and how many came back as a RetentionResult.

Mounting

On Cloudflare Workers, Bun and Vercel, export analytik.app.fetch or the app itself. On Node, use @hono/node-server. For Next.js, Express, Nuxt, SvelteKit, Astro and Cloudflare Pages Functions, see the framework guides. To nest it in an existing Hono app:

import { Hono } from 'hono'

const app = new Hono()
app.route('/', analytik.app) // routes keep their basePath, /api by default

The /event and /attribution routes have open CORS. Event bodies are limited to 8 KB.