Web Analytics API
Web Analytics is coming soon
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
Endpoint
| Site | URL |
|---|---|
| Hosted on Hubfly space | POST https://<your domain>/.hubfly/a/api/v1/events |
| Hosted elsewhere | POST https://hfa.<region>.hubfly.app/api/v1/events |
Send events
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"
}]}'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.
| Field | Required | Meaning |
|---|---|---|
type | Yes | event or pageview. |
name | For events | Event name, up to 120 characters. |
url | Yes | Absolute http(s) page URL on one of the site's domains. |
props | No | Up to 30 props, as in the browser. |
revenue | No | {"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. |
referrer | No | Referrer URL, for pageviews. |
ip, user_agent | No | The visitor's IP and user agent, used for the visitor hash, location, device and bot filtering, then discarded. |
visitor_id | No | Your own stable visitor id. |
user_id | No | Your user id. Use an opaque id, never an email address. |
timestamp | No | RFC 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:
visitor_id;- the same daily cookieless hash the script uses, when both
ipanduser_agentare present, so server and browser events from one person on one day count as one visitor; - a hash of
user_id; - 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
| Status | Meaning |
|---|---|
202 | {"accepted": n, "rejected": m}. Rejected events failed validation, were filtered or were not collected; they are never billed. |
400 | Invalid JSON or body shape. Nothing was recorded. |
401 | Missing, unknown or revoked ingest key. |
413 | The 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:
| Route | What it does | Permission |
|---|---|---|
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 /usage | Events this month, the free allowance, collection state and billable events per site. Cost fields only for members who can view billing. | project:read |
GET /routes | The domains the project serves on Hubfly space, and which of them already have a site. | network:manage |
POST /domains/verify | Starts or checks the DNS TXT verification of a domain hosted elsewhere. | project:edit |
PUT /settings | Sets or removes the monthly event cap (monthlyEventCap). | billing:manage |
POST /sites/create | Adds 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/status | One site, and whether its events arrive. | project:read |
PUT /sites/:siteId/update | Name, 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/delete | Deletes the site and its data. | project:edit |
POST /sites/:siteId/query | Runs a report; see run a report. | project:read |
GET /sites/:siteId/export | from, 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 /funnels | Goals and funnels. | Listing project:read, changes project:edit |
GET /sites/:siteId/segments, POST …/segments/create, DELETE …/segments/:segmentId/delete | Saved filters. | Listing project:read, changes project:edit |
GET /sites/:siteId/shares, POST …/shares/create, POST …/shares/:shareId/revoke | Read-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/revoke | Ingest keys. create returns the key once, in key. | project:edit, listing included |
Two groups of routes sit outside a project:
GET /api/v1/analytics/regionslists 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/unlockandPOST …/shared/:slug/queryread a shared dashboard. They take no credential: the link is the secret. A password-protected link answers queries only with the 24-hour token thatunlockreturns, 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 withX-Hubfly space-Subaccountand holding thesubaccounts:operatescope, and sub-account keys (hfsk_…) call every route under/api/v1/projects/:projectId/analyticsfor the sub-account's projects. They can create a standalone Analytics project withPOST /api/v1/projects/create, using"type": "analytics"and aregionId. - Platform and sub-account keys cannot call
GET /api/v1/analytics/regions. They can callGET /api/v1/regionsinstead: Web Analytics is offered whereproducts.analyticsis 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.
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"]}]
}'rangeis{"period": …}(today,7d,30d,month,6moor12mo) or{"from": "2026-10-01", "to": "2026-10-28"}, in the site's time zone.filterstake a dimension, anop(is,is_not,contains,not_containsormatches) and a list of values.segmentIdapplies a saved segment, andcompareisprevious_periodoryear_over_year.- Dimensions:
page,entry_page,exit_page,source,referrer,channel, theutm_*fields,country,region,city,browser,browser_version,os,os_version,device,language,hostname,event,goalandprop:<key>. - Filtered reports read raw events, kept for the site's retention.
meta.partialandmeta.coveredFromsay 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.
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);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"])
}| TypeScript | Go | Route |
|---|---|---|
analytics.regions() | Analytics.Regions | GET /api/v1/analytics/regions |
analytics.get, usage, routes | Analytics.Get, Usage, Routes | GET /, /usage, /routes |
analytics.verifyDomain, setEventCap | Analytics.VerifyDomain, SetEventCap | POST /domains/verify, PUT /settings |
analytics.sites.list, create, get, update, pause, resume, delete, status | Analytics.Sites.List, Create, Get, Update, Pause, Resume, Delete, Status | /sites/…; list reads GET / |
analytics.sites.query, realtime, export | Analytics.Sites.Query, Realtime, Export | POST /sites/:siteId/query (realtime runs type: "realtime"), GET /sites/:siteId/export |
analytics.goals, funnels, segments | Analytics.Goals, Funnels, Segments | list, create, update (goals and funnels only) and delete |
analytics.shares, keys | Analytics.Shares, Keys | list, create and revoke |
analytics.shared.get, unlock, query | Analytics.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.