ClearAnalytics

API Documentation

Access your ClearAnalytics data programmatically. Build integrations, dashboards, and export data to your data warehouse.

Authentication

All API requests require a Bearer token. Create tokens in your Settings → API Tokens page.

bash 
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://clearanalytics.eu/api/v1/stats/overview

Rate Limiting

API requests are limited to 60 requests per minute per token. When you exceed this limit, the API returns a 429 status code.

Base URL

https://clearanalytics.eu/api/v1

Stats Endpoints

Retrieve aggregated analytics data for your site.

GET /stats/overview

Get an overview of key metrics including visitors, pageviews, bounce rate, and average session duration.

Parameters

Name Type Required Description
period string No Time period: 24h, 7d, 30d, 90d, 12m (default: 7d)
from date No Start date (YYYY-MM-DD). Overrides period.
to date No End date (YYYY-MM-DD). Required if from is set.

Example Response

json 
{
  "data": {
    "visitors": 1523,
    "pageviews": 4891,
    "bounce_rate": 42.3,
    "avg_duration": 187,
    "visitors_change": 12.5,
    "pageviews_change": 8.2,
    "bounce_rate_change": -3.1,
    "avg_duration_change": 15.7
  }
}
GET /stats/timeseries

Get daily time series data for visitors and pageviews.

Parameters

Name Type Required Description
period string No Time period: 24h, 7d, 30d, 90d, 12m (default: 7d)
from date No Start date (YYYY-MM-DD)
to date No End date (YYYY-MM-DD)

Example Response

json 
{
  "data": [
    { "date": "2026-02-12", "visitors": 234, "pageviews": 567 },
    { "date": "2026-02-13", "visitors": 289, "pageviews": 612 }
  ]
}
GET /stats/pages

Get top pages ranked by pageviews.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
limit integer No Number of results, 1-100 (default: 10)

Example Response

json 
{
  "data": [
    { "pathname": "/", "visitors": 890, "pageviews": 1234, "avg_duration": 45 },
    { "pathname": "/pricing", "visitors": 456, "pageviews": 567, "avg_duration": 120 }
  ]
}
GET /stats/referrers

Get top referrer sources.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
limit integer No Number of results (default: 10)

Example Response

json 
{
  "data": [
    { "referrer_source": "google", "referrer": "google.com", "visitors": 345 },
    { "referrer_source": "social", "referrer": "twitter.com", "visitors": 123 }
  ]
}
GET /stats/browsers

Get browser usage statistics.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
limit integer No Number of results (default: 10)

Example Response

json 
{
  "data": [
    { "browser": "Chrome", "visitors": 678 },
    { "browser": "Safari", "visitors": 345 }
  ]
}
GET /stats/operating-systems

Get operating system usage statistics.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
limit integer No Number of results (default: 10)

Example Response

json 
{
  "data": [
    { "os": "macOS", "visitors": 456 },
    { "os": "Windows", "visitors": 389 }
  ]
}
GET /stats/devices

Get device type distribution (desktop, mobile, tablet).

Parameters

Name Type Required Description
period string No Time period (default: 7d)

Example Response

json 
{
  "data": [
    { "device_type": "desktop", "visitors": 678 },
    { "device_type": "mobile", "visitors": 456 },
    { "device_type": "tablet", "visitors": 89 }
  ]
}
GET /stats/languages

Get visitor language distribution from browser settings.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
limit integer No Number of results (default: 10)

Example Response

json 
{
  "data": [
    { "language": "en", "visitors": 456 },
    { "language": "de", "visitors": 234 },
    { "language": "nl", "visitors": 189 }
  ]
}
GET /stats/campaigns

Get UTM campaign performance data.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
limit integer No Number of results (default: 10)

Example Response

json 
{
  "data": [
    { "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "feb-2026", "visitors": 234, "pageviews": 567 }
  ]
}

E-commerce Stats Endpoints

Access e-commerce analytics including revenue, products, conversion funnels, and revenue attribution by traffic source.

GET /stats/ecommerce/overview

Get e-commerce overview metrics including revenue, transactions, average order value, and conversion rate with comparison changes.

Parameters

Name Type Required Description
period string No Time period: 24h, 7d, 30d, 90d, 12m (default: 7d)
from date No Start date (YYYY-MM-DD). Overrides period.
to date No End date (YYYY-MM-DD). Required if from is set.

Example Response

json 
{
  "data": {
    "revenue": 12450.00,
    "transactions": 156,
    "avg_order_value": 79.81,
    "conversion_rate": 3.2,
    "revenue_change": 18.5,
    "transactions_change": 12.3,
    "avg_order_value_change": 5.6,
    "conversion_rate_change": 0.4
  }
}
GET /stats/ecommerce/revenue-timeseries

Get daily time series data for revenue and transaction counts.

Parameters

Name Type Required Description
period string No Time period: 24h, 7d, 30d, 90d, 12m (default: 7d)
from date No Start date (YYYY-MM-DD)
to date No End date (YYYY-MM-DD)

Example Response

json 
{
  "data": [
    { "date": "2026-02-12", "revenue": 1890.50, "transactions": 24 },
    { "date": "2026-02-13", "revenue": 2134.00, "transactions": 28 }
  ]
}
GET /stats/ecommerce/products

Get top products ranked by revenue, including quantity sold and order count.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
limit integer No Number of results, 1-100 (default: 10)

Example Response

json 
{
  "data": [
    { "item_name": "Pro Plan Annual", "revenue": 4788.00, "quantity": 12, "orders": 12 },
    { "item_name": "Business Plan Monthly", "revenue": 2394.00, "quantity": 38, "orders": 38 }
  ]
}
GET /stats/ecommerce/funnel

Get the e-commerce conversion funnel: view_item → add_to_cart → begin_checkout → purchase. Includes unique visitor counts and drop-off rates per step.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
from date No Start date (YYYY-MM-DD)
to date No End date (YYYY-MM-DD)

Example Response

json 
{
  "data": [
    { "step": "view_item", "label": "View Product", "visitors": 1200, "dropoff_rate": 0.0 },
    { "step": "add_to_cart", "label": "Add to Cart", "visitors": 340, "dropoff_rate": 71.7 },
    { "step": "begin_checkout", "label": "Begin Checkout", "visitors": 210, "dropoff_rate": 38.2 },
    { "step": "purchase", "label": "Purchase", "visitors": 156, "dropoff_rate": 25.7 }
  ]
}
GET /stats/ecommerce/revenue-by-source

Get revenue attribution by traffic source, showing which referrers drive the most revenue.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
limit integer No Number of results (default: 10)

Example Response

json 
{
  "data": [
    { "source": "google", "revenue": 5670.00, "transactions": 72 },
    { "source": "direct", "revenue": 3240.00, "transactions": 41 },
    { "source": "newsletter", "revenue": 1890.00, "transactions": 24 }
  ]
}

Goals Endpoints

Access your conversion goals and their completions.

GET /goals

List all configured goals.

Example Response

json 
{
  "data": [
    {
      "id": "01JMABC123",
      "name": "Signup Page Visit",
      "type": "url",
      "config": { "match_type": "exact", "path": "/signup" },
      "is_active": true,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  ]
}
GET /goals/{goal}/completions

Get completions for a specific goal.

Parameters

Name Type Required Description
period string No Time period (default: 7d)
limit integer No Number of results (default: 50)

Example Response

json 
{
  "data": [
    {
      "id": "01JMDEF456",
      "goal_id": "01JMABC123",
      "visitor_hash": "a1b2c3...",
      "pageview_id": "01JMGHI789",
      "created_at": "2026-02-17T14:22:00Z"
    }
  ],
  "meta": {
    "goal": { "id": "01JMABC123", "name": "Signup Page Visit", "type": "url" },
    "total": 42
  }
}

Export, BigQuery & Power BI

Export raw data in JSONL or CSV format. Integrate with BigQuery or Power BI using ready-made schemas and import scripts.

BigQuery Quick Start

  1. Download the schema: GET /export/bigquery-schema
  2. Create a BigQuery table using the schema
  3. Export data as JSONL: GET /export/pageviews?format=jsonl
  4. Load the JSONL file into BigQuery with bq load
bash 
# 1. Download schema and data
curl -H "Authorization: Bearer $TOKEN" \
     "https://clearanalytics.eu/api/v1/export/bigquery-schema" > schema.json

curl -H "Authorization: Bearer $TOKEN" \
     "https://clearanalytics.eu/api/v1/export/pageviews?format=jsonl&from=2026-01-01&to=2026-02-18" \
     > pageviews.jsonl

# 2. Create table and load data
bq mk --table your_project:analytics.pageviews schema.json
bq load --source_format=NEWLINE_DELIMITED_JSON \
     your_project:analytics.pageviews pageviews.jsonl

Power BI Quick Start

  1. Download the Power Query script: GET /export/powerbi-schema?format=pqm
  2. In Power BI Desktop, go to Get Data → Blank Query → Advanced Editor
  3. Paste the script and replace YOUR_API_TOKEN with your actual token
  4. Change the table name at the bottom of the script to load different datasets
bash 
# Download the Power Query M script
curl -H "Authorization: Bearer $TOKEN" \
     "https://clearanalytics.eu/api/v1/export/powerbi-schema?format=pqm" \
     > clearanalytics-powerbi.pq

# Or get the EDM type schema as JSON
curl -H "Authorization: Bearer $TOKEN" \
     "https://clearanalytics.eu/api/v1/export/powerbi-schema"

The Power Query script imports data via CSV and automatically applies the correct column types. Available tables: pageviews, goals, goal_completions, ecommerce_events.

GET /export/pageviews

Export raw pageview data as JSONL or CSV. Supports cursor-based pagination for large datasets.

Parameters

Name Type Required Description
format string No Export format: jsonl or csv (default: jsonl)
from date No Start date (default: 30 days ago)
to date No End date (default: today)
cursor string No Last record ID for pagination
limit integer No Records per request, max 10000 (default: 10000)

Example Response

json 
{"id":"01JM...","visitor_hash":"a1b2...","hostname":"example.com","pathname":"/","device_type":"desktop","duration":45,"created_at":"2026-02-17T14:22:00Z"}
{"id":"01JM...","visitor_hash":"c3d4...","hostname":"example.com","pathname":"/pricing","device_type":"mobile","duration":120,"created_at":"2026-02-17T14:23:00Z"}
GET /export/goals

Export all goals as JSONL or CSV.

Parameters

Name Type Required Description
format string No Export format: jsonl or csv (default: jsonl)

Example Response

json 
{"id":"01JM...","name":"Signup Page Visit","type":"url","config":{"match_type":"exact","path":"/signup"},"is_active":true,"created_at":"2026-01-15T10:30:00Z"}
GET /export/goal-completions

Export goal completions as JSONL or CSV.

Parameters

Name Type Required Description
format string No Export format: jsonl or csv (default: jsonl)
from date No Start date (default: 30 days ago)
to date No End date (default: today)
cursor string No Last record ID for pagination
limit integer No Records per request, max 10000 (default: 10000)

Example Response

json 
{"id":"01JM...","goal_id":"01JM...","visitor_hash":"a1b2...","pageview_id":"01JM...","created_at":"2026-02-17T14:22:00Z"}
GET /export/ecommerce-events

Export e-commerce transaction events as JSONL or CSV.

Parameters

Name Type Required Description
format string No Export format: jsonl or csv (default: jsonl)
from date No Start date (default: 30 days ago)
to date No End date (default: today)
cursor string No Last record ID for pagination
limit integer No Records per request, max 10000 (default: 10000)

Example Response

json 
{"id":"01JM...","visitor_hash":"a1b2...","session_hash":"c3d4...","event_type":"purchase","transaction_id":"TXN-001","value":49.99,"currency":"EUR","items":[...],"created_at":"2026-02-17T14:22:00Z"}
GET /export/bigquery-schema

Get BigQuery-compatible JSON schema definitions for all exportable tables.

Example Response

json 
{
  "pageviews": [
    { "name": "id", "type": "STRING", "mode": "REQUIRED" },
    { "name": "visitor_hash", "type": "STRING", "mode": "REQUIRED" },
    { "name": "hostname", "type": "STRING", "mode": "REQUIRED" },
    ...
  ],
  "goals": [...],
  "goal_completions": [...]
}
GET /export/powerbi-schema

Get Power BI-compatible schema with EDM types, or download a ready-to-use Power Query M script.

Parameters

Name Type Required Description
format string No Output format: json (schema) or pqm (Power Query M script). Default: json
base_url string No Base API URL for the Power Query script (default: auto-detected)

Example Response

json 
{
  "pageviews": [
    { "name": "id", "type": "Edm.String", "nullable": false },
    { "name": "visitor_hash", "type": "Edm.String", "nullable": false },
    { "name": "duration", "type": "Edm.Int64", "nullable": false },
    ...
  ],
  "goals": [...],
  "goal_completions": [...]
}

AI Search & MCP

ClearAnalytics exposes a Model Context Protocol (MCP) server that lets AI assistants query your analytics data directly. Ask questions like "How many visitors did I have last week?" and get data-backed answers.

Plan requirement: AI Search is available on Pro, Growth, and Business plans. Requires an API token with Sanctum authentication.

MCP Endpoint

https://clearanalytics.eu/mcp/analytics

Connect this URL in any MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.) using an API token for authentication.

Configuration

Add the following to your MCP client configuration (e.g. .mcp.json for Claude Code):

json 
{
  "mcpServers": {
    "clearanalytics": {
      "type": "url",
      "url": "https://clearanalytics.eu/mcp/analytics",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Available Tools

The MCP server exposes 12 read-only tools. All tools require a tenant parameter (your tenant slug) and support optional period and domain filters.

Tool Description
list-sites List available websites. Use first to discover valid domain names.
analytics-overview Key metrics: visitors, pageviews, bounce rate, and average session duration with period comparison.
top-pages Top pages by pageviews with visitor counts and average duration.
traffic-sources Traffic source breakdown: direct, organic, social, referral, and top referring websites.
device-and-browser Device types, browsers, and operating systems by unique visitors.
languages Visitor language breakdown from browser settings.
campaigns UTM campaign performance: source, medium, campaign, visitors, and pageviews.
goals Conversion goals with completion counts and recent conversions.
ecommerce-overview Revenue, transactions, average order value, and conversion rate with comparison.
ecommerce-products Top products, e-commerce funnel, and revenue by traffic source.
daily-breakdown Daily visitor and pageview counts for trend analysis.
hourly-breakdown Visitor counts by hour of day (0–23) for peak traffic analysis.

In-Dashboard AI Chat

Pro, Growth, and Business plan users also get an AI-powered chat directly in the analytics dashboard. Click the AI button in the bottom-right corner to ask natural language questions about your data. The assistant uses the same 12 tools above to query your analytics and responds with data-backed answers and visualizations.

Error Codes

Status Code Description
401 Missing or invalid API token.
403 Insufficient permissions.
404 Resource not found.
422 Validation error. Check the error messages in the response body.
429 Rate limit exceeded. Wait and retry after the reset window.
500 Internal server error. Contact support if this persists.

Code Examples

JavaScript / Node.js

javascript 
const response = await fetch('https://clearanalytics.eu/api/v1/stats/overview?period=30d', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json',
  },
});

const { data } = await response.json();
console.log(`Visitors: ${data.visitors}, Pageviews: ${data.pageviews}`);

PHP

php 
$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://clearanalytics.eu/api/v1/stats/overview', ['period' => '30d']);

$data = $response->json('data');
echo "Visitors: {$data['visitors']}, Pageviews: {$data['pageviews']}";

Python

python 
import requests

response = requests.get(
    'https://clearanalytics.eu/api/v1/stats/overview',
    params={'period': '30d'},
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
)

data = response.json()['data']
print(f"Visitors: {data['visitors']}, Pageviews: {data['pageviews']}")

E-commerce Funnel (JavaScript)

javascript 
// Get the e-commerce conversion funnel
const funnel = await fetch('https://clearanalytics.eu/api/v1/stats/ecommerce/funnel?period=30d', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json',
  },
});

const { data } = await funnel.json();
data.forEach(step => {
  console.log(`${step.label}: ${step.visitors} visitors (${step.dropoff_rate}% drop-off)`);
});

// Get revenue attribution by source
const revenue = await fetch('https://clearanalytics.eu/api/v1/stats/ecommerce/revenue-by-source?period=30d', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' },
});

const sources = await revenue.json();
sources.data.forEach(s => {
  console.log(`${s.source}: €${s.revenue} (${s.transactions} orders)`);
});

Cursor Pagination (Python)

python 
import requests

headers = {'Authorization': 'Bearer YOUR_API_TOKEN'}
cursor = None
all_rows = []

while True:
    params = {'format': 'jsonl', 'from': '2026-01-01', 'to': '2026-02-20', 'limit': 10000}
    if cursor:
        params['cursor'] = cursor

    response = requests.get('https://clearanalytics.eu/api/v1/export/pageviews', params=params, headers=headers)
    lines = response.text.strip().split('\n')

    if not lines or lines == ['']:
        break

    import json
    rows = [json.loads(line) for line in lines]
    all_rows.extend(rows)
    cursor = rows[-1]['id']

    if len(rows) < 10000:
        break

print(f"Exported {len(all_rows)} pageviews")