Developer docs

Install an SDK, send one event, and watch it land in your workspace before the kettle has boiled. Everything below runs on the same API our own dashboards are built on — no private endpoints, no hidden rate tiers.

Quickstart Guides API reference Rate limits & errors API changelog Data handling

Quickstart

Three steps to your first event.

Get a sandbox workspace

Install the SDK

Pick the runtime closest to where your events already live. Server-side is preferable for anything that touches money — it survives ad blockers and it cannot be tampered with in the browser.

JavaScriptterminal

npm i @aurora/analytics
# or: pnpm add @aurora/analytics

Pythonterminal

pip install aurora-analytics

Goterminal

go get github.com/aurorahq/aurora-go

Initialise and track

Your write key lives in the workspace settings under Data sources. Keep it in an environment variable — a write key in a public repository gets rotated by our secret scanner within minutes, and you will get an email about it.

JavaScriptsrc/analytics.ts

import { Aurora } from '@aurora/analytics';

const aurora = new Aurora({
  writeKey: process.env.AURORA_WRITE_KEY,
  region: 'eu-west-2',        // London. Use 'eu-central-1' for Frankfurt.
});

await aurora.track({
  userId: 'usr_8f21c4',
  event: 'checkout_started',
  properties: {
    basket_value: 148.50,
    currency: 'GBP',
    storefront: 'uk',
    items: 3,
  },
});

Pythonanalytics.py

import os
from aurora import Aurora

aurora = Aurora(
    write_key=os.environ["AURORA_WRITE_KEY"],
    region="eu-west-2",
)

aurora.track(
    user_id="usr_8f21c4",
    event="checkout_started",
    properties={
        "basket_value": 148.50,
        "currency": "GBP",
        "storefront": "uk",
        "items": 3,
    },
)

Goanalytics.go

client := aurora.New(aurora.Config{
    WriteKey: os.Getenv("AURORA_WRITE_KEY"),
    Region:   "eu-west-2",
})
defer client.Close()

err := client.Track(ctx, aurora.Event{
    UserID: "usr_8f21c4",
    Name:   "checkout_started",
    Properties: map[string]any{
        "basket_value": 148.50,
        "currency":     "GBP",
        "storefront":   "uk",
    },
})

Shellraw HTTP

curl https://api.aurora.io/v1/events \
  -H "Authorization: Bearer $AURORA_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -H "Aurora-Version: 2026-05-01" \
  -d '{"event":"checkout_started","user_id":"usr_8f21c4",
       "properties":{"basket_value":148.50,"currency":"GBP"}}'

Region defaults to eu-west-2 (London). Enterprise workspaces pinned to Frankfurt should pass eu-central-1 — see data residency.

Watch it land

Open the live debugger in your workspace and the event appears within a couple of seconds, with any rejected properties listed alongside the reason. Nothing is silently dropped — a property that fails schema validation is routed to the debug queue where you can inspect and replay it.

09:32:11ingest — checkout_started accepted — usr_8f21c4 (eu-west-2)

09:32:11schema — All 5 properties validated against catalogue v41

09:32:14schema — plan_upgraded — unknown property "tier_name", routed to debug queue

09:32:19sync — Snowflake destination up to date — lag 38s

09:33:02webhook — hook_4471 returned 503 — retry 1 of 5 in 30s

JSONPOST /v1/events

{
  "event": "checkout_started",
  "user_id": "usr_8f21c4",
  "anonymous_id": "anon_5b1e77a9",
  "timestamp": "2026-07-14T09:32:11Z",
  "context": {
    "region": "eu-west-2",
    "locale": "en-GB",
    "app_version": "4.8.1",
    "source": "web"
  },
  "properties": {
    "basket_value": 148.50,
    "currency": "GBP",
    "items": 3,
    "storefront": "uk",
    "delivery_option": "royal_mail_tracked_24"
  }
}

The payload

One shape, everywhere.

Every SDK serialises to the same JSON body, so an event sent from a Go service and one sent from the browser are indistinguishable downstream. Only event and one of user_id or anonymous_id are required — everything else is optional and typed.

Timestamps are ISO 8601 in UTC; we store the workspace timezone separately so reports never drift
Monetary properties are stored to the penny — pass 148.50, not a rounded integer
Send an Idempotency-Key and a retried request will never double-count

Field	Type	Required	Notes
event	string	Yes	Lowercase object_verb, past tense. Max 64 characters.
user_id	string	Conditional	Required unless anonymous_id is present. Never send an email address.
anonymous_id	string	Conditional	Stitched onto the profile when you later call /v1/alias.
timestamp	ISO 8601	No	Defaults to receipt time. Backdating beyond 30 days needs a backfill token.
context	object	No	Reserved keys: region, locale, app_version, source, ip.
properties	object	No	Up to 120 keys, 32kB serialised. Types enforced by the catalogue.

Guides

Seven things worth reading
before you instrument.

Client SDKs

First-party libraries for JavaScript/TypeScript, Python, Go, Ruby, Swift and Kotlin. The browser bundle is 8.2kB gzipped, batches events every two seconds, retries with exponential backoff and queues offline so a flaky connection on the Northern line never loses a conversion.

HTTP API

Everything the SDKs do, over plain REST against https://api.aurora.io/v1. Bearer authentication, JSON bodies, ISO 8601 timestamps in UTC, and a dated Aurora-Version header so an API change never lands on you unannounced.

Event schema design

Our house convention is object_verb in the past tense — checkout_started, plan_upgraded, invoice_paid. Register events in the typed catalogue, run aurora schema lint in CI, and a mistyped property gets caught in code review instead of three months into a broken dashboard.

Identity & aliasing

Track anonymously, then call alias when someone signs in and Aurora stitches the pre-signup session onto the known profile. Merge rules are deterministic and replayable, and a UK GDPR erasure request removes every event for that subject across the warehouse in one call.

Warehouse sync

Bidirectional sync to Snowflake, BigQuery and Redshift using incremental change-data-capture rather than nightly full-table scans. Schedule it, trigger it from the API, backfill a date range, and watch row counts and lag per destination in real time.

Webhooks

Subscribe to alert.triggered, forecast.updated, sync.failed and eleven more. Every payload is signed with HMAC SHA-256 in the X-Aurora-Signature header, retried five times over 24 hours with jitter, and replayable from the dashboard for the last 30 days.

Self-serve SQL

Read-only SQL over the modelled tables, with the semantic layer available as functions so metric("active_users") means the same thing in a query as it does on a dashboard. Every result carries its lineage, and revenue columns are stored in pence to keep GBP arithmetic exact.

API reference

A sample of the surface.

See what changed

Every endpoint sits under https://api.aurora.io/v1 and speaks JSON in both directions. Authentication is a bearer token scoped to a single workspace; server keys start sk_live_, browser keys start pk_live_ and can only write events.

Pin the Aurora-Version header to a date and that contract is frozen for you for at least eighteen months. Unpinned requests follow the latest version, which is the wrong choice for production.

HTTPrequest headers

Authorization: Bearer sk_live_9f3c1ad2b7e4
Content-Type: application/json
Aurora-Version: 2026-05-01
Idempotency-Key: 7c2f0e51-3d9a-4a2b-9d18-6b0f2e441c30

Method	Endpoint	Description
POST	/v1/events	Ingest a single event. Returns 202 with the assigned event id.
POST	/v1/events/batch	Ingest up to 500 events in one request. Partial success reported per item.
POST	/v1/identify	Attach or update traits on a known user profile.
POST	/v1/alias	Merge an anonymous id into a known user id after sign-in.
GET	/v1/events/:id	Fetch one ingested event, including rejected properties, for debugging.
GET	/v1/metrics/:key	Read a semantic-layer metric over a date range and optional breakdown.
POST	/v1/queries	Submit a read-only SQL query. Returns a query id immediately.
GET	/v1/queries/:id/results	Page through query results, 10,000 rows per page maximum.
GET	/v1/destinations	List warehouse destinations with sync status and lag.
POST	/v1/destinations/:id/sync	Trigger an out-of-schedule sync or a dated backfill.
GET	/v1/webhooks	List webhook endpoints and their delivery health.
DELETE	/v1/webhooks/:id	Remove a webhook endpoint. In-flight retries are cancelled.

Full reference, including every query parameter and response shape, is generated from the live schema and versioned alongside it. Ask your solutions engineer for access to the sandbox workspace and the OpenAPI document.

Rate limits & errors

What happens when you push.

Limits by plan

Plan	Ingestion	Query API	Batch size
Starter	60 req/min	20 req/min	100 events
Growth	600 req/min	120 req/min	500 events
Enterprise	Custom	Custom	500 events

Status	Meaning
400	Malformed JSON or a missing required field.
401	Missing, revoked or wrong-type API key.
403	Key lacks scope for this endpoint or workspace.
413	Body above 1MB, or a property above 32kB.
422	Schema validation failed. Rejected keys are named in the body.
429	Rate limited. Honour Retry-After before trying again.
503	Region failover in progress. Safe to retry with the same idempotency key.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. The SDKs read those headers and back off for you; if you are calling the API directly, please do the same rather than retrying in a tight loop. Sustained 429s never cost you data — buffer locally and replay.

Cannot find it?

Ask a person instead.

SolutionsTalk to a solutions engineer about your schema — bring a sample payload and we will model it live↗ Emaildevelopers@aurora.io — SDK bugs, API questions, OpenAPI access↗ ChangelogEvery API and SDK change, dated and versioned — breaking changes get eighteen months of notice↗ SecurityEncryption, residency and sub-processors — for the questionnaire your legal team just sent you↗ PricingEvent allowances and rate limits by plan — Starter through Enterprise↗

Want a sandbox
and a sample dataset?

We will spin up a workspace with your own events flowing through it, usually within a day of the call.

Book a demo See pricing