APIs and integrations: analytics that plays well with others

When I introduced Tracely back in April, one of the founding principles was "composable, not a walled garden." This week I want to show what that actually looks like now that the machine-facing surfaces have filled in: a read API for pulling aggregates out, a Management API for automating the workspace itself, and data sources for bringing external analytics in.

Reading your data out

Every site can issue API tokens from its settings. A token is scoped to one site, carries explicit abilities (read, export), and can optionally have an expiry and an IP allowlist. Tracely stores only a SHA-256 hash of the secret — the plain value is shown once at creation, and last_used_at updates on every request so you can spot stale credentials.

With a read token you get the aggregate endpoints under /api/v1:

• GET /api/v1/stats — pageviews, visitors, sessions, bounce rate, and average duration for a period (today, 7d, 30d, 90d, 12m)
• GET /api/v1/pages and GET /api/v1/sources — top pages and referrer sources
• GET /api/v1/events — custom event counts, visitors, and revenue
• GET /api/v1/live — distinct visitors in the last five minutes

Authentication is a plain header: Authorization: Bearer YOUR_TOKEN_SECRET. No OAuth dance for a cron job that just wants last week's numbers.

For anything the fixed endpoints don't cover, there's a small reporting API: GET /api/v1/reports/schema returns the allowlisted dimensions and metrics per resource, and POST /api/v1/reports/run takes a resource, date bounds, dimensions, and metrics and returns rows. It is deliberately not a Google Analytics Data API clone — the schema and allowlists are Tracely's own — but it covers the "group pageviews by X and give me Y" class of questions without me having to predict every combination.

The export ability unlocks bulk paths: paginated exports of raw pageviews, events, performance samples, and heatmap buckets (JSON or NDJSON with cursor pagination), a manifest endpoint that documents every field, and async export jobs that produce gzipped NDJSON for the big pulls. Exported rows omit internal IDs so they re-import cleanly. If you ever want to leave, this is the door, and it's unlocked.

Automating the workspace

Site tokens read analytics; they can't create sites. For that there's a separate Management API at /api/management/v1, authenticated with organization-level tokens that carry their own abilities — teams:read, sites:write, members:invite, and so on. It covers teams, sites, members, and invitations: list teams, create a site with a domain and timezone, invite someone with a role, revoke a pending invitation.

The point of splitting the two is blast radius. A BI pipeline holding a read token for one site cannot touch your team roster, and a Terraform run provisioning sites doesn't need access to any analytics data. Mutations go to the audit log, and plan limits apply the same as in the web app — the API is not a side door around seat counts.

There's also an API & integrations hub in the app that lists your sites with links to token management, plus the organization's Management API, webhooks, and SCIM screens, so you don't have to remember where each credential lives.

External data, sitting beside your own

The third piece runs the other direction. Data sources let you connect external analytics — most usefully a Google Analytics 4 property via OAuth — and sync aggregates into Tracely on a schedule (tracely:sync-ga4-analytics pulls reports for every site with a connected property). CSV import handles historical backfills.

The design rule I care most about here: external data is never merged into your first-party totals. GA4 aggregates appear in dedicated cards labeled as external, so you read the two side by side instead of wondering which methodology produced a blended number. That matters during a migration, when you want to watch Tracely's numbers ramp against GA4's for a few weeks before you trust them. If that's the situation you're in, I wrote up the process at /migrate/google-analytics.

Why this order

It would have been easy to leave APIs for "later" and polish dashboards instead. But an analytics tool that can't be scripted against ends up trapping your data by inertia, even with good intentions. Building the read, export, and management surfaces early keeps me honest: every number on the dashboard has to be reachable by a curl command, and every workspace object has to be manageable without clicking. The full surface is summarized on /features; the request-level details live in the in-app API docs.