API Endpoints

Browser analytics endpoints and the connected backend telemetry API.

Backend telemetry and Node SDK

Services connects a project and environment to a separate server-only ingest key. Existing public website tracking IDs remain unchanged and cannot authorize backend writes. Start the Node SDK before importing HTTP or logger modules. Keep keys out of browser bundles, HTML and URLs.

Open Backend → Connection setup for installation and Agent connection for a query token. Backend-only projects are supported. Queries include evaluated scope/range, coverage and freshness; unavailable observations are not zero traffic. Public website shares never expose backend telemetry.

Node SDK installation

For a connected website, open Backend → Connection setup. For an independent backend, open Projects & services and create a project. Save the Details step, follow Install, then use Verify to check for a received request. Website tracking is installed separately from the website installation guide.

Install the published @pipetrace/sdk-node package with your package manager and commit the lockfile. The guide provides server variables and the startup command for your actual compiled entrypoint. Keep the backend key in runtime secret settings.

Self-hosted operators can alternatively distribute the versioned archive advertised by /sdk/manifest.json. The API build prepares this archive. Verify the manifest's SHA-512 integrity and pin the version; this operator distribution path is separate from the npm instructions shown in setup.

For ESM, use node --experimental-loader @pipetrace/sdk-node/hook bootstrap.mjs; the bootstrap starts the SDK, then dynamically imports the application. Set PIPETRACE_ENDPOINT, PIPETRACE_API_KEY and PIPETRACE_SERVICE_NAME. Services provides the complete bootstrap example. Native OpenTelemetry HTTP exporters can also send directly without the wrapper.

See backend data and redaction and retention and deletion for the separate browser/backend policies.

Sites

List Sites

GET /api/v1/sites

Returns all sites for the authenticated user.

Get Site

GET /api/v1/sites/:siteId

Create Site

POST /api/v1/sites

{
  "domain": "example.com",
  "name": "My Website",
  "jurisdiction": "PT"
}

jurisdiction is optional: the ISO 3166-1 alpha-2 code of the country where the site's owner is established. With it, the site starts with consent required everywhere, anonymous counts before consent and 25 months of retention. Without it, the site keeps the behaviour from before privacy settings until you save them.

Update Site

PATCH /api/v1/sites/:siteId

{
  "name": "Updated Name"
}

Site Privacy Settings

PUT /api/v1/sites/:siteId/privacy

{
  "jurisdiction": "PT",
  "consentMode": "required",
  "preConsentTier": "counts",
  "retentionMonths": 25
}

Replaces the site's whole privacy policy; every field is required and unknown fields are rejected. jurisdiction is the owner's ISO 3166-1 alpha-2 country code. consentMode is required or regional. preConsentTier is off, counts or sessions. retentionMonths is a whole number from 1 to 25. Returns the updated site. A regional policy for an owner established in the EEA, the UK, Gibraltar, the Channel Islands, the Isle of Man or Switzerland is rejected with 400 REGIONAL_NOT_ALLOWED. New events follow a saved policy within 5 minutes.

Delete Site

DELETE /api/v1/sites/:siteId

Tracker policy answers

The tracker asks GET /api/v1/policy?site=… before it collects anything, and every POST /api/v1/track response with a body carries the same answer as policy (a Global Privacy Control request gets 204 with no body):

{ "maxTier": 0, "stop": "policy", "cap": "dnt" }

• maxTier is the highest privacy tier the server will store for this visitor: 0 (nothing), 1 (anonymous counts), 2 (anonymous sessions) or 3 (consented analytics).
• stop appears only with maxTier: 0. "gpc" means the browser sent Global Privacy Control: nothing is collected, and no consent lifts it. "policy" means the site records nothing before consent: an explicit pipetrace.consent("granted") can still start consented analytics on the same page, unless cap is "dnt".
• cap: "dnt" appears when the request carried Do Not Track: the visitor stays at most at anonymous counts, even after accepting, and the tracker does not keep cookies or browser storage for them.

Both fields are optional and additive; older trackers ignore them.

Analytics

Overview

GET /api/v1/sites/:siteId/analytics/overview?period=7d

Returns aggregate statistics for the period.

{
  "data": {
    "visitors": 1234,
    "pageviews": 5678,
    "bounceRate": 45.2,
    "avgDuration": 180,
    "visitorsChange": 12.5,
    "pageviewsChange": 8.3,
    "tiers": {
      "visits": { "anonymousCounts": 340, "anonymousSessions": 210, "consented": 900 },
      "pageviews": { "anonymousCounts": 500, "anonymousSessions": 480, "consented": 4698 },
      "visitors": { "anonymousSessions": 210, "consented": 1024 }
    }
  }
}

tiers is optional and additive: existing fields keep their meaning across every privacy tier, and a caller reading only the old fields keeps working unchanged. See Privacy tiers and metrics below for what each field counts.

Time Series

GET /api/v1/sites/:siteId/analytics/timeseries?period=7d

Returns data points for charts.

Top Pages

GET /api/v1/sites/:siteId/analytics/pages?period=7d&limit=10

Pages are ranked by reach (visitors plus anonymous-count page views). Add sort=pageviews to pick and order the top pages by page views instead; sort=reach is the default.

Top Sources

GET /api/v1/sites/:siteId/analytics/sources?period=7d&limit=10

Devices

GET /api/v1/sites/:siteId/analytics/devices?period=7d

Browsers

GET /api/v1/sites/:siteId/analytics/browsers?period=7d

Live Count

GET /api/v1/sites/:siteId/analytics/live

Returns activity in the last 5 minutes:

{
  "data": { "count": 7, "visitors": 7, "anonymousPageviews": 2 }
}

visitors counts consented and anonymous-session visitors (tiers 2–3); anonymousPageviews counts anonymous-count (tier 1) page views in the same window, which have no visitor to count. count keeps its earlier meaning for existing consumers and always equals visitors. Because tier 1 timestamps are truncated to the minute they were received, the anonymous-page-view window can be off by up to a minute.

Privacy tiers and metrics

Pipetrace can count a visit before consent is given (see privacy tiers and data). Every analytics response keeps counting the same way across tiers, so these rules apply everywhere above:

• Visits are the entry pageview of an anonymous-count (tier 1) visitor, or the session of an anonymous-session or consented (tier 2–3) visitor. A consented continuation — a session that started when someone upgraded consent mid-visit — is not counted again; it was already counted anonymously.
• Visitors only exist for anonymous-session and consented visits (tiers 2–3). Anonymous counts (tier 1) have no visitor ID, so they add to visits and page views but never to visitors. An anonymous-session visitor is daily: its ID changes at UTC midnight, so the same person on two days is two visitors, and a session that crosses midnight is two visits.
• Goal conversion rate is converting visits ÷ visits, capped at 100%. An anonymous-count goal is counted per page rather than per visit, and a consented continuation's conversion is credited to the visit already counted anonymously, so the rate can be approximate where those apply.
• Bounce rate, average duration, scroll depth and Core Web Vitals are only ever measured for consented visits (tier 3).
• Journeys, paths and funnels use anonymous-session and consented visits (tiers 2–3). A consented journey can start on the page where consent was given, not the original landing page.
• Page, source, UTM, country, device and browser lists are ranked by how many visits and visitors reached that value, so an anonymous-count-only value can still appear and rank. Operating system is reported for consented visits only.

Use filter_privacy_tier to restrict any of the above to one collection method.

Query Parameters

HTTP Status Codes