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"
}

Update Site

PATCH /api/v1/sites/:siteId

{
  "name": "Updated Name"
}

Delete Site

DELETE /api/v1/sites/:siteId

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
  }
}

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

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 the number of visitors in the last 5 minutes.

Query Parameters

HTTP Status Codes