Hubfly spaceDocs
Console

Web Analytics API

Web Analytics is coming soon

Web Analytics is not open for new sites yet, and nothing is charged for it. This guide describes how it works at launch; the prices are the launch prices.

Web Analytics has two APIs. The events API takes events from your servers, authenticated with an ingest key of one site. The Dashboard API manages sites and reads their reports with a personal access token or a platform key, and the TypeScript and Go SDKs wrap it.

Send events from your backend when the browser cannot: purchases confirmed by a payment webhook, signups completed in an API, or pageviews from a server-rendered app that does not run the script. Server-side events are counted and billed like browser events.

Ingest keys

Create a key in the site's Settings → Ingest keys, or with hubfly analytics keys create. It starts with hfak_, belongs to one site and is shown once; Hubfly space keeps only a hash. A site can have up to 20 active keys. A new key works once it reaches the site's region, usually within a few minutes. Revoking a key takes effect the same way, and requests that use it then fail with 401.

Keep it on your servers

An ingest key lets anyone who holds it send events that you pay for. Store it as a secret environment variable and never put it in browser code; the script needs no key.

Endpoint

SiteURL
Hosted on Hubfly spacePOST https://<your domain>/.hubfly/a/api/v1/events
Hosted elsewherePOST https://hfa.<region>.hubfly.app/api/v1/events

Send events

bash
curl https://hfa.<region>.hubfly.app/api/v1/events \
  -H "Authorization: Bearer $HUBFLY_ANALYTICS_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "type": "event",
    "name": "Purchase",
    "url": "https://example.com/checkout",
    "props": {"plan": "pro"},
    "revenue": {"amount": "29.99", "currency": "USD"},
    "ip": "203.0.113.9",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/605.1.15",
    "timestamp": "2026-10-29T10:00:00Z"
  }]}'
TypeScript
await fetch("https://hfa.<region>.hubfly.app/api/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HUBFLY_ANALYTICS_INGEST_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    events: [{ type: "event", name: "Signup", url: "https://example.com/register", user_id: "user_42" }],
  }),
});

Fields

The body is a JSON object with an events array of 1 to 100 events, at most 256 KiB in total.

FieldRequiredMeaning
typeYesevent or pageview.
nameFor eventsEvent name, up to 120 characters.
urlYesAbsolute http(s) page URL on one of the site's domains.
propsNoUp to 30 props, as in the browser.
revenueNo{"amount": "29.99", "currency": "USD"}, with the amount as a number or a decimal string and the site's currency when currency is left out. Unlike in the browser, it must be an object: an event whose revenue is a bare number is rejected.
referrerNoReferrer URL, for pageviews.
ip, user_agentNoThe visitor's IP and user agent, used for the visitor hash, location, device and bot filtering, then discarded.
visitor_idNoYour own stable visitor id.
user_idNoYour user id. Use an opaque id, never an email address.
timestampNoRFC 3339 time, from 24 hours in the past to 5 minutes in the future. Defaults to now.

How visitors are counted

Hubfly space uses the first of these that the event carries:

  1. visitor_id;
  2. the same daily cookieless hash the script uses, when both ip and user_agent are present, so server and browser events from one person on one day count as one visitor;
  3. a hash of user_id;
  4. otherwise each event counts as its own visitor.

Forward the visitor's real IP and user agent from the incoming request when you have them, not your server's own.

Responses and limits

StatusMeaning
202{"accepted": n, "rejected": m}. Rejected events failed validation, were filtered or were not collected; they are never billed.
400Invalid JSON or body shape. Nothing was recorded.
401Missing, unknown or revoked ingest key.
413The body is larger than 256 KiB.

Server-side events go through the same filters as browser events, including a limit of 120 events per minute for each site and IP address. Send the visitor's IP rather than your server's, so that one busy server does not hit that limit.

Dashboard API

Sites, settings and reports are part of the Dashboard API at https://api.hubfly.space, with the usual {"ok": true, "data": …} response envelope. Each route needs the listed permission in the project. Paths in this table are relative to /api/v1/projects/:projectId/analytics:

RouteWhat it doesPermission
GET /The project's sites with their settings and install snippets, whether new sites can be added, and the monthly event cap.project:read
GET /usageEvents this month, the free allowance, collection state and billable events per site. Cost fields only for members who can view billing.project:read
GET /routesThe domains the project serves on Hubfly space, and which of them already have a site.network:manage
POST /domains/verifyStarts or checks the DNS TXT verification of a domain hosted elsewhere.project:edit
PUT /settingsSets or removes the monthly event cap (monthlyEventCap).billing:manage
POST /sites/createAdds a site: "source": "external" with its domains, or "hubfly_route" with one of the project's routes.project:edit, plus network:manage for Hubfly space domains
GET /sites/:siteId, GET /sites/:siteId/statusOne site, and whether its events arrive.project:read
PUT /sites/:siteId/updateName, domains, time zone, currency, retention, visitor identity, tracking settings, state (active or paused) and script injection.project:edit, plus network:manage for injection
DELETE /sites/:siteId/deleteDeletes the site and its data.project:edit
POST /sites/:siteId/queryRuns a report; see run a report.project:read
GET /sites/:siteId/exportfrom, to, kind (events, sessions or summaries) and format (csv or ndjson). At most 8 MB per call; truncated is true beyond that.project:read
GET /sites/:siteId/goals, POST …/goals/create, PUT …/goals/:goalId/update, DELETE …/goals/:goalId/delete, and the same under /funnelsGoals and funnels.Listing project:read, changes project:edit
GET /sites/:siteId/segments, POST …/segments/create, DELETE …/segments/:segmentId/deleteSaved filters.Listing project:read, changes project:edit
GET /sites/:siteId/shares, POST …/shares/create, POST …/shares/:shareId/revokeRead-only dashboard links, with an optional password and expiry.Listing project:read, changes project:edit
GET /sites/:siteId/keys, POST …/keys/create, POST …/keys/:keyId/revokeIngest keys. create returns the key once, in key.project:edit, listing included

Two groups of routes sit outside a project:

  • GET /api/v1/analytics/regions lists the regions where you can create a standalone Analytics project. Any signed-in user may call it.
  • GET /api/v1/analytics/shared/:slug, POST …/shared/:slug/unlock and POST …/shared/:slug/query read a shared dashboard. They take no credential: the link is the secret. A password-protected link answers queries only with the 24-hour token that unlock returns, and shared dashboards cannot export or use saved segments and funnels.

Tokens and platform keys

  • Personal access tokens (hf_…) call every route above with the permissions of the person who created them. A token with scopes also needs the scope listed for the route, and a token pinned to projects reaches only those. Billing permissions cannot be token scopes, so only a token without scopes can set the event cap.
  • Platform keys (hfpk_…), sent with X-Hubfly space-Subaccount and holding the subaccounts:operate scope, and sub-account keys (hfsk_…) call every route under /api/v1/projects/:projectId/analytics for the sub-account's projects. They can create a standalone Analytics project with POST /api/v1/projects/create, using "type": "analytics" and a regionId.
  • Platform and sub-account keys cannot call GET /api/v1/analytics/regions. They can call GET /api/v1/regions instead: Web Analytics is offered where products.analytics is true, except in Mail regions. See the sub-account API guide for the headers.

Run a report

POST …/sites/:siteId/query runs one report. type is aggregate, timeseries, breakdown, goals, funnel, journeys, vitals, errors, props or realtime, and the shape of data follows it.

bash
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/analytics/sites/$SITE_ID/query" \
  -H "Authorization: Bearer $HUBFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "breakdown",
    "dim": "page",
    "limit": 10,
    "metrics": ["visitors", "pageviews"],
    "range": {"period": "30d"},
    "filters": [{"dim": "country", "op": "is", "values": ["DE"]}]
  }'
  • range is {"period": …} (today, 7d, 30d, month, 6mo or 12mo) or {"from": "2026-10-01", "to": "2026-10-28"}, in the site's time zone.
  • filters take a dimension, an op (is, is_not, contains, not_contains or matches) and a list of values. segmentId applies a saved segment, and compare is previous_period or year_over_year.
  • Dimensions: page, entry_page, exit_page, source, referrer, channel, the utm_* fields, country, region, city, browser, browser_version, os, os_version, device, language, hostname, event, goal and prop:<key>.
  • Filtered reports read raw events, kept for the site's retention. meta.partial and meta.coveredFrom say when a range starts before them.

SDK

The SDKs wrap the Dashboard API: hubfly.analytics in the TypeScript SDK (@hubfly/sdk) and client.Analytics in the Go SDK. Both read a personal access token or machine credential from HUBFLY_TOKEN. The browser tracker is a separate package, @hubfly/analytics.

TypeScript
import { HubflyClient } from "@hubfly/sdk";

const hubfly = new HubflyClient();

const { data: site } = await hubfly.analytics.sites.create(projectId, {
  source: "external",
  domain: "example.com",
  retentionDays: 90,
});
console.log(site.install.snippet); // the <script> tag for every page

const { data: pages } = await hubfly.analytics.sites.query(projectId, site.id, {
  type: "breakdown",
  dim: "page",
  limit: 10,
  range: { period: "30d" },
});
for (const row of pages.results) console.log(row.value, row.values.visitors);
Go
client := hubfly.NewClient()

resp, err := client.Analytics.Sites.Query(ctx, projectID, siteID, hubfly.AnalyticsQuery{
    Type:  "breakdown",
    Dim:   "page",
    Limit: hubfly.Float(10),
    Range: &hubfly.AnalyticsRangeInput{Period: "30d"},
})
if err != nil {
    log.Fatal(err)
}
rows, _ := resp.Data.BreakdownResults()
for _, row := range rows {
    fmt.Println(row.Value, row.Values["visitors"])
}
TypeScriptGoRoute
analytics.regions()Analytics.RegionsGET /api/v1/analytics/regions
analytics.get, usage, routesAnalytics.Get, Usage, RoutesGET /, /usage, /routes
analytics.verifyDomain, setEventCapAnalytics.VerifyDomain, SetEventCapPOST /domains/verify, PUT /settings
analytics.sites.list, create, get, update, pause, resume, delete, statusAnalytics.Sites.List, Create, Get, Update, Pause, Resume, Delete, Status/sites/…; list reads GET /
analytics.sites.query, realtime, exportAnalytics.Sites.Query, Realtime, ExportPOST /sites/:siteId/query (realtime runs type: "realtime"), GET /sites/:siteId/export
analytics.goals, funnels, segmentsAnalytics.Goals, Funnels, Segmentslist, create, update (goals and funnels only) and delete
analytics.shares, keysAnalytics.Shares, Keyslist, create and revoke
analytics.shared.get, unlock, queryAnalytics.Shared.Get, Unlock, Query/api/v1/analytics/shared/:slug…, without a credential

Errors carry the API's codes, such as ANALYTICS_DOMAIN_UNVERIFIED for a domain that is not verified yet and ANALYTICS_UNAVAILABLE when a region does not take new sites. They are listed in AnalyticsErrorCodes in TypeScript and as hubfly.ErrCodeAnalytics… constants in Go. From a terminal, hubfly analytics covers sites, stats, exports, usage and ingest keys.

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top