REST API Introduction

The DataSaaS REST API gives you programmatic access to your analytics data — visitors, pageviews, revenue, goals, funnels, and more. Use it to build custom dashboards, feed data into BI tools, or integrate analytics into your workflows.

Quick start

Get up and running in 3 steps:

Go to Settings → API and create an API key
Copy your key (you'll only see it once)
Make your first request:

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 in the Authorization header:

Authorization: Bearer ds_live_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6

API keys are created in your website's Settings → API tab. Each key is scoped to a single website and has either Read only or Read & Write permissions.

Warning

Treat your API key like a password. Never expose it in client-side code, public repositories, or shared environments.

Base URL

https://datasaas.co/api/v1

All endpoints are prefixed with /api/v1. The version number will only change for breaking changes.

Common parameters

Most analytics endpoints accept these query parameters:

Parameter	Type	Required	Description
site_id	string	Yes	Your website identifier (e.g., `ds_abc123`)
start	string	No	ISO 8601 start date. Defaults to 30 days ago
end	string	No	ISO 8601 end date. Defaults to now
timezone	string	No	IANA timezone (e.g., America/New_York). Defaults to UTC
limit	number	No	Number of results, 1-1000. Defaults to 100
offset	number	No	Pagination offset. Defaults to 0

Filtering

Filter results using bracket syntax on query parameters. Each filter specifies a dimension, an operator, and a value:

# Visitors from the US using Chrome
?country[is]=United States&browser[is]=Chrome

# Pages containing "/blog" but not from Safari
?pathname[contains]=/blog&browser[is_not]=Safari

Operator	Description
is	Exact match
is_not	Exclude exact match
contains	Substring match (case-insensitive)
not_contains	Exclude substring match

Available dimensions: country, region, city, browser, os, device_type, referrer, pathname, hostname, utm_source, utm_medium, utm_campaign, utm_term, utm_content, channel

Rate limits

API requests are rate-limited per API key:

Endpoint type	Limit
Read endpoints (breakdowns, lists)	3,000 requests / hour
Aggregation queries (overview, timeseries)	300 requests / hour
Write endpoints (goals, payments)	600 requests / hour

Every response includes rate limit headers:

X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2847
X-RateLimit-Reset: 1711461600

When rate limited, you'll receive a 429 response with a Retry-After header indicating how many seconds to wait.

Response format

All successful responses use this envelope:

{
  "results": [ ... ],
  "meta": {
    "date_range": {
      "start": "2026-03-01T00:00:00.000Z",
      "end": "2026-03-26T23:59:59.000Z"
    },
    "timezone": "UTC",
    "limit": 100,
    "offset": 0,
    "count": 25
  }
}

Errors

Errors follow the RFC 9457 Problem Details format:

{
  "type": "https://datasaas.co/docs/errors/unauthorized",
  "status": 401,
  "title": "Unauthorized",
  "detail": "Missing or malformed Authorization header",
  "instance": "/api/v1/overview"
}

Status	Description
400	Missing required parameters or invalid values
401	Missing, invalid, expired, or revoked API key
403	Insufficient permissions (wrong scope or plan)
404	Website or resource not found
429	Rate limit exceeded
500	Internal server error

Endpoint reference

Full documentation for each endpoint group:

Section	Endpoints
Analytics	overview, timeseries, pages, entry-pages, exit-pages, referrers, channels, campaigns, countries, regions, cities, browsers, os, devices
Visitors	visitor list, visitor profile, visitor journey
Goals & Revenue	goals list, create goal, goal completions, revenue overview, revenue timeseries, create payment
Realtime	visitor count, active visitor details
Funnels	funnel list, funnel conversion data

Script Configuration

Analytics