# DataSaaS Documentation
Generated from https://datasaas.co/docs
---
# Get Started in 4 Steps
Set up DataSaaS analytics on your website in minutes. Track traffic, find your best marketing channels, and connect it all to revenue.
## 1. Install the tracking script
Paste this snippet inside the of every page you want to track:
```html
```
Replace YOUR_WEBSITE_ID with the ID from adding your website, and yourdomain.com with your domain.
The script is lightweight, zero external dependencies, loads with defer, and supports SPA navigation via the History API.
Platform guides: https://datasaas.co/docs/install-html · https://datasaas.co/docs/install-nextjs · https://datasaas.co/docs/install-npm
## 2. Verify installation
Visit your site, open the DataSaaS dashboard, and confirm realtime visitors or onboarding's green check. Bots, headless browsers, and DNT visitors are filtered automatically.
## 3. Connect a revenue source (optional)
Supported providers:
- Stripe — Checkout API, Payment Links, PaymentIntent
- LemonSqueezy — Checkout API, Payment Links
- Polar — Checkout API
- Paddle — Checkout API, Overlay Checkout
See https://datasaas.co/docs/payment-providers and https://datasaas.co/docs/revenue-overview.
## 4. Explore the dashboard
One-screen analytics: sources, pages, geography, devices, goals, revenue per visitor, funnels. Growth plan unlocks the 27-endpoint REST API (https://datasaas.co/docs/api).
---
# Connect Payment Providers
Connect Stripe, LemonSqueezy, Polar, or Paddle so every payment is attributed to the visitor, source, campaign, and page that produced it.
## Overview
1. Dashboard → Settings → Revenue
2. Choose provider and complete connection (API key or OAuth as documented per provider)
3. Ensure visitor_id is linked at checkout (auto-injected for some providers; pass client_reference_id / metadata for others)
## Guides
- Stripe: https://datasaas.co/docs/revenue-stripe
- LemonSqueezy: https://datasaas.co/docs/revenue-lemonsqueezy
- Polar: https://datasaas.co/docs/revenue-polar
- Paddle: https://datasaas.co/docs/revenue-paddle
- Concepts: https://datasaas.co/docs/revenue-overview
Custom providers: POST /api/v1/payments with visitor_id, amount, currency, transaction_id (write API key).
---
# Tracking Parameters (UTMs)
Use UTM parameters and ad click IDs to track which campaigns drive traffic and revenue.
[See full content at https://datasaas.co/docs/utms]
---
# Filter Your Data
Drill down into specific segments of your analytics with powerful filters.
[See full content at https://datasaas.co/docs/filters]
---
# Track Custom Goals
Measure signups, purchases, and any action that matters to your business.
[See full content at https://datasaas.co/docs/goals]
---
# All Installation Guides
Install DataSaaS on any platform — frameworks, CMS, website builders, AI builders, and more.
[See full content at https://datasaas.co/docs/install-all-guides]
---
# HTML / Script Tag
Install DataSaaS on any HTML website with a script tag.
## Steps
1. Get your tracking snippet from DataSaaS after adding a website.
```html
```
2. Paste it inside before .
3. Visit your site and confirm events in the dashboard within seconds.
Cookieless variant: https://datasaas.co/js/script.cookieless.min.js (see script configuration docs).
---
# NPM SDK / Package
Install the DataSaaS TypeScript/JavaScript SDK for React, Next.js, Vue, and other frameworks.
```bash
npm install @datasaas/datasaas
```
Initialize with your website ID and domain, or load the script tag. See https://datasaas.co/docs/install-npm for framework-specific wiring, identify(), and goal tracking.
```js
import { datasaas } from "@datasaas/datasaas";
// or load script.min.js and use window.datasaas.goal / identify
```
---
# Next.js
Install DataSaaS in Next.js (App Router or Pages Router).
## App Router
Add the script in app/layout.tsx:
```tsx
// In or via next/script with strategy afterInteractive / beforeInteractive stub
```
SPA route changes are tracked automatically via History API interception.
## Revenue
When creating Stripe Checkout sessions, pass client_reference_id: visitor id from the datasaas_visitor_id cookie or window.datasaas.visitor_id.
Full guide: https://datasaas.co/docs/install-nextjs
---
# React Router
Add DataSaaS analytics to your React application using React Router. The tracking script works automatically with client-side routing.
Method 1: Root Component
---
// App.jsx
import { useEffect } from "react";
import { BrowserRouter, Routes, Route } from "react-router-dom";
function App() {
useEffect(() => {
const script = document.createElement("script");
script.defer = true;
script.dataset.websiteId = "ds_YOUR_WEBSITE_ID";
script.dataset.domain = "yourdomain.com";
script.src = "https://datasaas.co/js/script.min.js";
document.head.appendChild(script);
return () => {
document.head.removeChild(script);
};
}, []);
return (
} />
{/* ... your routes */}
);
}
export default App;
Method 2: HTML File
---
My App
Note: The DataSaaS script automatically detects SPA navigation via the History API. No additional configuration is needed for client-side routing.
Verify
---
Visit your React (React Router) site, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Vue.js
Add DataSaaS analytics to your Vue.js application. Works with both Vue 2 and Vue 3.
Method 1: Entry File
---
// main.js
import { createApp } from "vue";
import App from "./App.vue";
const script = document.createElement("script");
script.defer = true;
script.dataset.websiteId = "ds_YOUR_WEBSITE_ID";
script.dataset.domain = "yourdomain.com";
script.src = "https://datasaas.co/js/script.min.js";
document.head.appendChild(script);
createApp(App).mount("#app");
Method 2: HTML File
---
My Vue App
Note: The DataSaaS script automatically detects SPA navigation via the History API. No additional configuration is needed for client-side routing.
Verify
---
Visit your Vue.js site, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Astro
Add DataSaaS analytics to your Astro website. Astro's layout system makes it easy to add tracking across all pages.
Method 1: Layout Component (Recommended)
---
---
// src/layouts/Layout.astro
interface Props {
title: string;
}
const { title } = Astro.props;
---
{title}
Method 2: Individual Pages
---
My Page
Hello, world!
Verify
---
Visit your Astro site, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Django
Add DataSaaS analytics to your Django application. You can add the script directly to your base template or use a settings-driven approach.
Method 1: Base Template
---
{% block title %}My Site{% endblock %}
{% block head %}
{% endblock %}
{% block content %}{% endblock %}
Method 2: Django Settings
---
# settings.py
DATASAAS_WEBSITE_ID = "ds_YOUR_WEBSITE_ID"
Method 2 (continued): Template
---
Verify
---
Visit your Django site, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Laravel
Add DataSaaS analytics to your Laravel application using Blade templates and environment configuration.
Method 1: Blade Layout
---
@yield('title', 'My App')
@yield('content')
Method 2: Environment Config
---
env('DATASAAS_WEBSITE_ID', 'ds_YOUR_WEBSITE_ID'),
];
Method 2 (continued): .env
---
# .env
DATASAAS_WEBSITE_ID=ds_YOUR_WEBSITE_ID
Verify
---
Visit your Laravel site, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# WordPress
Add DataSaaS analytics to your WordPress site. You can use a plugin (recommended) or edit your theme files directly.
Method 1: Plugin (Recommended)
---
Method 2: Manual (header.php)
---
Verify
---
Visit your WordPress site, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Shopify
Install DataSaaS on your Shopify store via theme code or Custom Pixel.
[See full content at https://datasaas.co/docs/install-shopify]
---
# Webflow
Add DataSaaS analytics to your Webflow site. No code required — just paste the tracking snippet into your project settings.
Installation
---
1. Open Project Settings
2. Go to Custom Code
3. Paste in the Head Code section
4. Save and Publish
5. Add the DataSaaS tracking script
6. Replace the placeholder values
Replace ds_YOUR_WEBSITE_ID with your Website ID and yourdomain.com with your actual domain.
Verify
---
7. Visit your website, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Framer
Add DataSaaS analytics to your Framer site with a single snippet in your site settings.
Installation
---
1. Open Site Settings
2. Navigate to General
3. Paste in the "End of tag" section
4. Save
5. Add the DataSaaS tracking script
6. Replace the placeholder values
Replace ds_YOUR_WEBSITE_ID with your Website ID and yourdomain.com with your actual domain.
Verify
---
7. Visit your website, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Ghost CMS
Add DataSaaS analytics to your Ghost blog. Ghost has built-in code injection that makes this straightforward.
Installation
---
1. Go to Code injection
2. Paste in Site Header
3. Save
4. Add the DataSaaS tracking script
5. Replace the placeholder values
Replace ds_YOUR_WEBSITE_ID with your Website ID and yourdomain.com with your actual domain.
Verify
---
6. Visit your website, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Wix
Add DataSaaS analytics to your Wix website. Wix lets you add custom code through the site settings.
Warning: Adding custom code requires a Wix Premium plan. Make sure your account is on a paid plan before proceeding.
Installation
---
1. Open Custom Code settings
2. Add new custom code
3. Configure placement
4. Apply
5. Add the DataSaaS tracking script
6. Replace the placeholder values
Replace ds_YOUR_WEBSITE_ID with your Website ID and yourdomain.com with your actual domain.
Verify
---
7. Visit your website, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# SquareSpace
Add DataSaaS analytics to your Squarespace website using the built-in Code Injection feature.
Warning: Adding custom code requires a SquareSpace Business plan or higher. Make sure your account is on a paid plan before proceeding.
Installation
---
1. Open Code Injection
2. Paste in the Header section
3. Save
4. Add the DataSaaS tracking script
5. Replace the placeholder values
Replace ds_YOUR_WEBSITE_ID with your Website ID and yourdomain.com with your actual domain.
Verify
---
6. Visit your website, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Bubble
Add DataSaaS analytics to your Bubble application. Bubble allows you to add custom scripts via the SEO settings.
Warning: Adding custom code requires a Bubble paid plan. Make sure your account is on a paid plan before proceeding.
Installation
---
1. Open SEO / metatags settings
2. Paste in the header script section
3. Save
4. Add the DataSaaS tracking script
5. Replace the placeholder values
Replace ds_YOUR_WEBSITE_ID with your Website ID and yourdomain.com with your actual domain.
Verify
---
6. Visit your website, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Podia
Add DataSaaS analytics to your Podia website to track your course and digital product traffic.
Installation
---
1. Open Website Code settings
2. Paste in the section
3. Save
4. Add the DataSaaS tracking script
5. Replace the placeholder values
Replace ds_YOUR_WEBSITE_ID with your Website ID and yourdomain.com with your actual domain.
Verify
---
6. Visit your website, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Kajabi
Add DataSaaS analytics to your Kajabi site to understand where your audience comes from.
Installation
---
1. Open Site Details
2. Open Custom Code
3. Paste in Header Code
4. Save
5. Add the DataSaaS tracking script
6. Replace the placeholder values
Replace ds_YOUR_WEBSITE_ID with your Website ID and yourdomain.com with your actual domain.
Verify
---
7. Visit your website, then open the DataSaaS dashboard. You should see your visit appear within a few seconds.
---
# Google Tag Manager
Install DataSaaS via Google Tag Manager with a custom HTML tag.
[See full content at https://datasaas.co/docs/install-gtm]
---
# Lovable
Install DataSaaS on a Lovable AI-built website with a prompt template.
[See full content at https://datasaas.co/docs/install-lovable]
---
# Bolt
Install DataSaaS on a Bolt AI-built application with a prompt template.
[See full content at https://datasaas.co/docs/install-bolt]
---
# Vercel v0
Install DataSaaS on a Vercel v0 AI-generated application.
[See full content at https://datasaas.co/docs/install-v0]
---
# Replit
Install DataSaaS on a Replit project using Replit Agent.
[See full content at https://datasaas.co/docs/install-replit]
---
# React Native / Expo
Install the DataSaaS SDK in your React Native / Expo mobile application.
[See full content at https://datasaas.co/docs/install-react-native]
---
# Revenue Attribution
Revenue attribution is DataSaaS's core differentiator: which traffic sources generate paying customers.
## How it works
Visitor arrives → DataSaaS assigns visitor_id
→ Visitor browses (tracked)
→ Checkout receives visitor_id
→ Payment completes
→ DataSaaS matches payment to visitor
→ Revenue attributed to original source
The tracking script can inject datasaas_visitor_id into checkout URLs for supported providers. You can also pass it manually.
## Reading the visitor ID
```javascript
const visitorId = window.datasaas?.visitor_id
// or document.cookie match datasaas_visitor_id=
```
Provider guides: Stripe, LemonSqueezy, Polar, Paddle under /docs/revenue-*.
---
# Stripe
Connect Stripe to attribute payments to traffic sources.
## Setup
1. Dashboard → Settings → Revenue → Stripe
2. Enter Stripe Secret Key (sk_live_ or sk_test_). Encrypted at rest; server-side only.
3. Pass visitor ID on Checkout Session:
```js
const session = await stripe.checkout.sessions.create({
client_reference_id: visitorId, // datasaas_visitor_id
line_items: [{ price: "price_xxx", quantity: 1 }],
mode: "payment",
success_url: "https://yourdomain.com/success",
cancel_url: "https://yourdomain.com/cancel",
});
```
4. Make a test purchase; revenue should appear attributed in the dashboard.
Supports Checkout, Payment Links, PaymentIntent, subscriptions/MRR. Full guide: https://datasaas.co/docs/revenue-stripe
---
# LemonSqueezy
Set up revenue attribution with LemonSqueezy Checkout and Payment Links.
[See full content at https://datasaas.co/docs/revenue-lemonsqueezy]
---
# Polar
Set up revenue attribution with Polar Checkout.
[See full content at https://datasaas.co/docs/revenue-polar]
---
# Paddle
Set up revenue attribution with Paddle Checkout.
[See full content at https://datasaas.co/docs/revenue-paddle]
---
# Dashboard Guide
Learn about every card, chart, and metric in your DataSaaS dashboard.
[See full content at https://datasaas.co/docs/dashboard-guide]
---
# Script Configuration
Advanced tracking script options.
## Script attributes
| Attribute | Required | Description |
|-----------|----------|-------------|
| data-website-id | Yes | Website id (ds_…) |
| data-domain | Recommended | Domain validation; events dropped on mismatch |
| data-api | No | Custom events endpoint (default origin + /api/events) |
| data-allow-localhost | No | "true" to track localhost |
| defer | Recommended | Non-blocking load |
## SPA support
Automatic via pushState, popstate, hashchange. Works with Next.js, React Router, Vue Router, SvelteKit, etc.
## Outbound links
External link clicks fire _outbound events automatically.
## Other features
Scroll depth, ad click IDs (gclid etc.), bot filtering, Do Not Track respect, declarative goals, JS API (goal, identify, reset), cookieless mode, prerender/BFCache handling.
Full detail: https://datasaas.co/docs/script-configuration
---
# Bot & AI Crawler Tracking
The DataSaaS JavaScript tag tracks humans. AI crawlers are different: they fetch your raw HTML and never run JavaScript, so no browser tag can ever see them. That is why bot tracking is a separate, server-side install. It does not replace script.js, it runs alongside it. Add one non-blocking call in your backend, middleware, or edge and DataSaaS identifies and IP-verifies every crawler for you.
Every tracking call returns immediately. It never blocks your response and never throws into your request path, and it sends nothing for ordinary human traffic. It also returns a promise that settles once the report lands, which serverless runtimes need. See "Serverless and edge runtimes" below.
## What gets tracked
Four search crawlers do render JavaScript, so the JS tag already captures them through the events beacon with no server code: Googlebot, Google-InspectionTool, Bingbot, and Applebot.
Every AI crawler needs the server package, because none of them run JavaScript. That includes GPTBot, ClaudeBot, Claude-User, PerplexityBot, Perplexity-User, CCBot, Amazonbot, Bytespider, the Meta crawlers, xAI / Grok, Mistral, Cohere, DeepSeek, and more.
DataSaaS recognizes 56 crawlers, grouped into four categories: AI answers (assistants that cite your pages live), Search index (traditional search engines), Training (dataset collection), and Other. See the full crawler directory at https://datasaas.co/crawlers for every operator, its category, and how it is verified.
## Install
npm install @datasaas/bot-tracker
Replace ds_abc123 in the snippets below with the website id from Settings > Tracking.
## Next.js (middleware)
Match pages, not static assets, since bots crawl pages and not build chunks.
```ts
// middleware.ts
import { NextResponse } from "next/server";
import { trackBotFromRequest } from "@datasaas/bot-tracker";
export function middleware(req: Request) {
trackBotFromRequest(req, { websiteId: "ds_abc123" }); // fire-and-forget
return NextResponse.next();
}
// Match pages, not static assets. Bots crawl pages, not chunks.
export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
```
## Express / Node
```js
import { trackBotRequest } from "@datasaas/bot-tracker";
app.use((req, res, next) => {
trackBotRequest(
{
userAgent: req.headers["user-agent"] || "",
ip: (req.headers["x-forwarded-for"]?.split(",")[0] || req.socket.remoteAddress || "").trim(),
path: req.path,
host: req.headers.host,
method: req.method,
},
{ websiteId: "ds_abc123" }
);
next();
});
```
## Hono
```ts
import { Hono } from "hono";
import { trackBotRequest } from "@datasaas/bot-tracker";
const app = new Hono();
app.use("*", async (c, next) => {
trackBotRequest(
{
userAgent: c.req.header("user-agent") || "",
ip: (c.req.header("x-forwarded-for")?.split(",")[0] || "").trim(),
path: new URL(c.req.url).pathname,
host: c.req.header("host"),
method: c.req.method,
},
{ websiteId: "ds_abc123" }
);
await next();
});
```
## Cloudflare Workers
trackBotFromRequest accepts the Web Request directly. On Workers, the adapter reads the real client IP from the cf-connecting-ip header for you. Workers hand the execution context to your handler rather than exposing it globally, so pass the returned promise to ctx.waitUntil.
```ts
import { trackBotFromRequest } from "@datasaas/bot-tracker";
export default {
async fetch(request, env, ctx) {
// The adapter reads the real client IP from cf-connecting-ip.
ctx.waitUntil(trackBotFromRequest(request, { websiteId: "ds_abc123" }));
return fetch(request);
},
};
```
## Any other framework
For Fastify, Bun, Deno, or anything else, build the fields yourself and call trackBotRequest. The endpoint option defaults to https://datasaas.co/api/bot. Override it only when you self-host DataSaaS and want to point at your own instance.
```ts
import { trackBotRequest } from "@datasaas/bot-tracker";
trackBotRequest(
{ userAgent, ip, path, host, method },
{ websiteId: "ds_abc123", endpoint: "https://datasaas.co/api/bot" }
);
```
## Serverless and edge runtimes
On a long-running server (a VPS, a container, plain Node) an un-awaited report finishes on its own and there is nothing to do. Serverless and edge platforms are different: they freeze the invocation the moment you return a response, which cancels any request still in flight. Both tracking functions return a promise that settles when the report lands, so you can keep the runtime alive until it does.
- Vercel and Next.js are handled automatically. The package registers the report on the Next request context for you.
- Cloudflare Workers need ctx.waitUntil(trackBotFromRequest(...)), since the context is passed to your handler.
- Other serverless platforms take the same promise in whatever keep-alive primitive they expose.
If you deploy to a serverless or edge runtime and ignore the returned promise, reports are cancelled before they leave and your bot traffic silently stays empty. On a long-running server you can ignore it safely.
## Verified vs unverified
Verification runs in two steps. First DataSaaS matches the request User-Agent against a known crawler. Then it checks the request IP against that operator's published CIDR ranges, which are refreshed daily. A request whose User-Agent claims to be GPTBot but comes from an IP outside OpenAI's ranges is recorded as unverified, so you can filter spoofed traffic out.
Some operators do not publish an IP list at all, so they can only ever be matched by User-Agent. These are marked ua_only and are always recorded as unverified by design. The dashboard defaults to showing verified crawlers only, with a toggle to include the rest. The verify methods are ip_range, reverse_dns, and ua_only.
Note: Operators without a published IP range (Meta, xAI, and most Chinese crawlers) are ua_only and always land as unverified. That is expected, not a misconfiguration.
## Where to find the data
Bot traffic shows up in the Bot traffic card on every site dashboard. It gives you category tabs (AI answers, Search index, Training, Other), a Verified only toggle that is on by default, Bots and Pages views to see which crawlers visited and which pages they hit, and a Discovery filter to isolate requests for robots.txt, llms.txt, and sitemaps.
---
# REST API Introduction
The DataSaaS REST API gives programmatic access to analytics data — visitors, pageviews, revenue, goals, funnels, and more. Use it to build custom dashboards, feed BI tools, or integrate analytics into your workflows.
## Quick start
1. Go to Settings → API and create an API key
2. Copy your key (shown once)
3. Make your first request:
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/overview?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"
```
## Authentication
All API requests require a Bearer token:
```bash
Authorization: Bearer ds_live_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6
```
Keys are created under Settings → API. Each key is scoped to one website with Read only or Read & Write permissions. Never expose keys in client-side code.
## Base URL
```
https://datasaas.co/api/v1
```
All endpoints are prefixed with /api/v1.
## Common parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| site_id | string | Yes | Website identifier (e.g. ds_abc123) |
| start | string | No | ISO 8601 start date. Default: 30 days ago |
| end | string | No | ISO 8601 end date. Default: now |
| timezone | string | No | IANA timezone. Default: UTC |
| limit | number | No | Results 1–1000. Default: 100 |
| offset | number | No | Pagination offset. Default: 0 |
## Filtering
Bracket syntax on query params:
```
?country[is]=United States&browser[is]=Chrome
?pathname[contains]=/blog&browser[is_not]=Safari
```
Operators: is, is_not, contains, not_contains.
Dimensions: country, region, city, browser, os, device_type, referrer, pathname, hostname, utm_source, utm_medium, utm_campaign, utm_term, utm_content, channel.
## Rate limits
| Type | Limit |
|------|-------|
| Read (breakdowns, lists) | 3,000 / hour |
| Aggregation (overview, timeseries) | 300 / hour |
| Write (goals, payments) | 600 / hour |
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. 429 includes Retry-After.
## Response format
```json
{
"results": [ ... ],
"meta": {
"date_range": { "start": "...", "end": "..." },
"timezone": "UTC",
"limit": 100,
"offset": 0,
"count": 25
}
}
```
## Errors (RFC 9457)
```json
{
"type": "https://datasaas.co/docs/errors/unauthorized",
"status": 401,
"title": "Unauthorized",
"detail": "Missing or malformed Authorization header",
"instance": "/api/v1/overview"
}
```
Status codes: 400, 401, 403, 404, 429, 500.
## Endpoint index (27 v1 routes)
Analytics: overview, timeseries, pages, entry-pages, exit-pages, referrers, channels, campaigns, countries, regions, cities, browsers, os, devices.
Visitors: list, profile, journey.
Goals & revenue: goals list/create, completions, revenue, revenue timeseries, payments create/delete.
Realtime: count, active visitors.
Funnels: list, conversion data.
Site: get, patch.
Full detail: https://datasaas.co/docs/api-analytics · https://datasaas.co/docs/api-visitors · https://datasaas.co/docs/api-goals-revenue · https://datasaas.co/docs/api-realtime · https://datasaas.co/docs/api-funnels
---
# Site Endpoints
Site metadata for the API-key-scoped website.
## GET /api/v1/site
Returns id (website_id), name, domain, timezone, created_at.
Params: site_id (req) or implied by key scope depending on deployment; always pass site_id.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/site?site_id=ds_abc123"
```
```json
{
"results": {
"id": "ds_abc123",
"name": "My SaaS",
"domain": "example.com",
"timezone": "UTC",
"created_at": "2026-01-15T10:00:00Z"
}
}
```
## PATCH /api/v1/site
Update name and/or settings. Write scope required.
Body: name (optional string), settings (optional object).
```bash
curl -X PATCH -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"My SaaS","settings":{"timezone":"America/New_York"}}' \
"https://datasaas.co/api/v1/site?site_id=ds_abc123"
```
```json
{
"results": {
"id": "ds_abc123",
"name": "My SaaS",
"timezone": "America/New_York"
}
}
```
---
# Analytics Endpoints
Read access to website analytics. All endpoints require Authorization Bearer and site_id.
## Common parameters
site_id (required), start, end, timezone, limit — see REST API Introduction.
## GET /api/v1/overview
Aggregate metrics: visitors, pageviews, bounce_rate, avg_duration, revenue, mrr, conversion_rate.
Params: site_id (req), start, end, timezone.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/overview?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"
```
```json
{
"results": {
"visitors": 12453,
"pageviews": 34211,
"bounce_rate": 0.42,
"avg_duration": 187,
"revenue": 24500.00,
"mrr": 8200.00,
"conversion_rate": 0.032
},
"meta": { "site_id": "ds_abc123", "start": "2026-03-01T00:00:00Z", "end": "2026-03-26T23:59:59Z", "timezone": "UTC" }
}
```
## GET /api/v1/timeseries
Time series by granularity.
Params: site_id (req), start, end, timezone, granularity (hour|day|week|month, default day).
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/timeseries?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&granularity=day"
```
```json
{
"results": [
{ "period": "2026-03-01", "visitors": 421, "pageviews": 1230 }
],
"meta": { "site_id": "ds_abc123", "granularity": "day" }
}
```
## GET /api/v1/pages
Top pages by pageviews.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/pages?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "pathname": "/", "pageviews": 5000, "visitors": 3200 } ] }
```
## GET /api/v1/entry-pages
First pageview per session.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/entry-pages?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "entry_page": "/", "visitors": 2800 } ] }
```
## GET /api/v1/exit-pages
Last pageview per session.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/exit-pages?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "exit_page": "/pricing", "visitors": 1200 } ] }
```
## GET /api/v1/referrers
Referrer domains ranked by visitors. Direct traffic is empty string.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/referrers?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "referrer": "google.com", "visitors": 4500 } ] }
```
## GET /api/v1/channels
Marketing channels (Organic Search, Paid Search, Social, Direct, Referral, Email).
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/channels?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"
```
```json
{ "results": [ { "channel": "Organic Search", "visitors": 6000 } ] }
```
## GET /api/v1/campaigns
UTM campaigns, sources, mediums, contents.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/campaigns?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{
"results": {
"campaigns": [ { "campaign": "spring_sale", "visitors": 2400, "pageviews": 5800 } ],
"sources": [ { "source": "google", "visitors": 3200 } ],
"mediums": [ { "medium": "cpc", "visitors": 2800 } ],
"contents": [ { "content": "hero_banner", "visitors": 900 } ]
}
}
```
## GET /api/v1/countries
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/countries?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "country": "United States", "visitors": 8000 } ] }
```
## GET /api/v1/regions
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/regions?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "region": "California", "visitors": 2000 } ] }
```
## GET /api/v1/cities
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/cities?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "city": "San Francisco", "visitors": 800 } ] }
```
## GET /api/v1/browsers
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/browsers?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "browser": "Chrome", "visitors": 7000 } ] }
```
## GET /api/v1/os
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/os?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "os": "macOS", "visitors": 5000 } ] }
```
## GET /api/v1/devices
device_type: desktop | mobile | tablet.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/devices?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{ "results": [ { "device_type": "desktop", "visitors": 9000 } ] }
```
---
# Visitor Endpoints
Visitor profiles, identity, and journey timelines. Requires Authorization and site_id.
## GET /api/v1/visitors
Paginated visitor list.
Params: site_id (req), start, end, timezone, limit (1–1000, default 100), offset.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/visitors?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=20&offset=0"
```
```json
{
"results": [
{
"visitor_id": "v_8f3a2b1c",
"country": "United States",
"city": "San Francisco",
"browser": "Chrome",
"os": "macOS",
"device_type": "desktop",
"referrer": "google.com",
"last_seen": "2026-03-25T14:32:00Z",
"pageview_count": 24,
"goal_count": 3,
"user_id": "usr_12345",
"display_name": "Jane Doe",
"email": "jane@example.com",
"custom_properties": { "plan": "pro" }
}
],
"meta": { "site_id": "ds_abc123", "limit": 20, "offset": 0, "total": 1243 }
}
```
## GET /api/v1/visitors/:id
Full profile including attribution and revenue. Path :id is visitor_id. No date range required.
Params: site_id (req), :id (path).
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/visitors/v_8f3a2b1c?site_id=ds_abc123"
```
```json
{
"results": {
"visitor_id": "v_8f3a2b1c",
"user_id": "usr_12345",
"display_name": "Jane Doe",
"email": "jane@example.com",
"country": "United States",
"first_seen": "2026-02-10T08:15:00Z",
"last_seen": "2026-03-25T14:32:00Z",
"total_visits": 18,
"total_pageviews": 124,
"referrer": "google.com",
"utm_source": "google",
"revenue": {
"total_paid": 299.00,
"payments": [
{ "amount": 99.00, "currency": "USD", "transaction_id": "txn_abc123", "product_name": "Pro Plan" }
],
"subscription": { "status": "active", "plan": "Pro Plan", "mrr": 99.00 }
}
}
}
```
## GET /api/v1/visitors/:id/journey
Chronological event timeline (pageviews, goals, etc.).
Params: site_id (req), :id (path).
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/visitors/v_8f3a2b1c/journey?site_id=ds_abc123"
```
```json
{
"results": [
{
"event_type": "pageview",
"pathname": "/",
"referrer": "google.com",
"session_id": "s_1a2b3c",
"timestamp": "2026-03-25T14:00:00Z"
},
{
"event_type": "pageview",
"pathname": "/pricing",
"session_id": "s_1a2b3c",
"timestamp": "2026-03-25T14:02:00Z"
}
]
}
```
---
# Goals & Revenue
Goals conversions, server-side goal events, revenue metrics, and custom payments. POST/DELETE require Read & Write API keys.
## GET /api/v1/goals
List goals with conversion stats for a date range.
Params: site_id (req), start, end, timezone, limit.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/goals?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"
```
```json
{
"results": [
{ "goal_name": "signup", "unique_visitors": 340, "completion_count": 412, "conversion_rate": 0.027 }
]
}
```
## POST /api/v1/goals
Server-side goal completion. Body fields: name (req), visitor_id (req), url, metadata. site_id as query param. Write scope required.
```bash
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"signup","visitor_id":"v_8f3a2b1c","url":"https://app.example.com/welcome","metadata":{"plan":"pro"}}' \
"https://datasaas.co/api/v1/goals?site_id=ds_abc123"
```
```json
{ "results": { "created": true, "goal_name": "signup" } }
```
## GET /api/v1/goals/:name/completions
Individual completions for a goal name (path).
Params: site_id (req), :name (path), start, end, timezone, limit.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/goals/signup/completions?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"
```
```json
{
"results": [
{
"visitor_id": "v_8f3a2b1c",
"completed_at": "2026-03-25T14:05:00Z",
"source": "google.com",
"country": "United States",
"browser": "Chrome"
}
]
}
```
## GET /api/v1/revenue
Revenue overview: total_revenue, mrr, conversion_rate. Amounts in dollars (not cents).
Params: site_id (req), start, end, timezone.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/revenue?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"
```
```json
{
"results": { "total_revenue": 24500.00, "mrr": 8200.00, "conversion_rate": 0.032 }
}
```
## GET /api/v1/revenue/timeseries
Revenue over time.
Params: site_id (req), start, end, timezone, granularity (hour|day|week|month).
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/revenue/timeseries?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&granularity=day"
```
```json
{
"results": [
{ "period": "2026-03-01", "new_revenue": 1200.00, "refund_revenue": 0.00 }
]
}
```
## POST /api/v1/payments
Record a payment and attribute it to a visitor (custom providers). Write scope.
Body: visitor_id (req), amount (req, dollars), currency (req, ISO 4217), transaction_id (req), payment_type (one_time|recurring|refund), product_name, paid_at. site_id as query param.
```bash
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"visitor_id":"v_8f3a2b1c","amount":99.00,"currency":"USD","transaction_id":"txn_abc123","payment_type":"recurring","product_name":"Pro Plan"}' \
"https://datasaas.co/api/v1/payments?site_id=ds_abc123"
```
```json
{ "results": { "created": true, "transaction_id": "txn_abc123" } }
```
## DELETE /api/v1/payments
Delete a payment recorded via the API (provider=api). Write scope.
Params: site_id (req query). Body: transaction_id (req).
```bash
curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"transaction_id":"txn_abc123"}' \
"https://datasaas.co/api/v1/payments?site_id=ds_abc123"
```
```json
{ "results": { "deleted": true } }
```
---
# Realtime Endpoints
Currently active visitors (last 90 seconds of activity).
## GET /api/v1/realtime
Live visitor count. Lightweight; poll every 10–15s.
Params: site_id (req). No date range.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/realtime?site_id=ds_abc123"
```
```json
{
"results": { "visitors": 42 },
"meta": { "site_id": "ds_abc123", "window_seconds": 90 }
}
```
## GET /api/v1/realtime/visitors
Active visitor details (location, device, page, identity if available).
Params: site_id (req).
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/realtime/visitors?site_id=ds_abc123"
```
```json
{
"results": [
{
"visitor_id": "v_8f3a2b1c",
"country": "United States",
"city": "San Francisco",
"browser": "Chrome",
"pathname": "/pricing",
"session_duration": 245,
"user_id": "usr_12345"
}
],
"meta": { "site_id": "ds_abc123", "window_seconds": 90, "total_active": 1 }
}
```
---
# Funnel Endpoints
Funnel definitions and conversion/drop-off data.
## GET /api/v1/funnels
List funnels and steps.
Params: site_id (req).
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/funnels?site_id=ds_abc123"
```
```json
{
"results": [
{
"id": "fnl_a1b2c3",
"name": "Signup Flow",
"funnel_steps": [
{ "name": "Landing Page", "step_type": "pageview", "step_order": 1 },
{ "name": "Pricing Page", "step_type": "pageview", "step_order": 2 },
{ "name": "Signup", "step_type": "goal", "step_order": 3 }
]
}
]
}
```
## GET /api/v1/funnels/:id
Conversion data for one funnel.
Params: site_id (req), :id (path), start (req), end (req), timezone.
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://datasaas.co/api/v1/funnels/fnl_a1b2c3?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"
```
```json
{
"results": {
"steps": [
{ "step_order": 1, "name": "Landing Page", "visitors": 5000, "drop_off": 2200, "conversion_from_prev": 1.0, "conversion_from_start": 1.0 },
{ "step_order": 2, "name": "Pricing Page", "visitors": 2800, "drop_off": 2050, "conversion_from_prev": 0.56, "conversion_from_start": 0.56 },
{ "step_order": 3, "name": "Signup", "visitors": 750, "drop_off": 0, "conversion_from_prev": 0.268, "conversion_from_start": 0.15 }
],
"overall_conversion": 0.15
}
}
```
---
# API Reference
Legacy and dashboard-adjacent HTTP endpoints (POST /api/events, filter values, etc.).
For the authenticated 27-endpoint REST API (base https://datasaas.co/api/v1), see:
- https://datasaas.co/docs/api — auth, rate limits, errors
- https://datasaas.co/docs/api-analytics
- https://datasaas.co/docs/api-visitors
- https://datasaas.co/docs/api-goals-revenue
- https://datasaas.co/docs/api-realtime
- https://datasaas.co/docs/api-funnels
Those pages are fully inlined (method, path, params, examples) in https://datasaas.co/llms-full.txt.
---
# Privacy & Security
How DataSaaS protects your data and your visitors' privacy.
[See full content at https://datasaas.co/docs/privacy-security]
---
# Troubleshooting
Fix common issues with event tracking, revenue, realtime, and more.
[See full content at https://datasaas.co/docs/troubleshooting]
---