Web Analytics

On this page, we'll explore the various endpoints that provide detailed web analytics data for your custom domains. From visitor counts and pageview statistics to traffic sources and user engagement metrics, these endpoints give you a complete picture of how users interact with your domains.

The web analytics API enables you to track and analyze key metrics including unique visitors, session data, page performance, user demographics, traffic sources, campaign effectiveness through UTM parameters, and device usage patterns. Whether you need high-level overview statistics or detailed behavioral insights, these endpoints provide the data you need to understand your audience and optimize your web presence.

Common Parameters

Analytics endpoints support the following common parameters:

Name
from
Type
string
Description
Start date for the analytics period in ISO 8601 format YYYY-MM-DD, e.g., "2024-01-01". If not provided, defaults to 30 days ago. Timezone is UTC.
Name
to
Type
string
Description
End date for the analytics period in ISO 8601 format YYYY-MM-DD, e.g., "2024-01-31". If not provided, defaults to current date. Timezone is UTC.
Name
frequency
Type
string
Description
(For time-series endpoints only) Time grouping frequency. Available values: day, week, month. Default: day. Ranges longer than 31 days return weekly data when you ask for day, and ranges longer than 181 days always return monthly data.

Time-series endpoints return one entry for every day, week or month in the range, including periods without traffic (value 0). Each key is the first day of its period: the date itself for day, the Monday for week, and the 1st for month.

Analytics data is available from July 1, 2025, and earlier dates return zeros. Responses are cached for up to 5 minutes.

Analytics must be enabled for the account that owns the domain, otherwise these endpoints return 403 Forbidden. A domain that doesn't belong to one of your accounts returns 404 Not Found.

How web analytics are counted

Web analytics only count pageviews: successful (2xx or 304) GET requests to paths without a file extension. Requests from known bots and datacenter IP addresses are excluded.
A visitor is a unique IP address. A visit is one visitor within one clock hour (UTC).
Visitor and visit counts are approximate, usually within 1–2% of the exact number.
List endpoints return up to 200 entries sorted by count. percentage is each entry's share of the returned entries' total.

Web Analytics

GET

/api/v1/analytics/custom_domains/:uuid/unique_visitors_count

Unique visitors count

This endpoint returns the total number of unique visitors for a custom domain within the specified time range.

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.

Request

GET

/api/v1/analytics/custom_domains/:uuid/unique_visitors_count

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/unique_visitors_count \
  -H "Authorization: Bearer {token}" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "count": 15234
}

GET

/api/v1/analytics/custom_domains/:uuid/unique_visitors_by_date

Unique visitors by date

This endpoint returns the number of unique visitors broken down by date.

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.
Name
frequency
Type
string
Description
Time grouping frequency (day, week, month). Default: day.

Request

GET

/api/v1/analytics/custom_domains/:uuid/unique_visitors_by_date

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/unique_visitors_by_date \
  -H "Authorization: Bearer {token}" \
  -d frequency="day" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "data": {
    "2024-01-01": 523,
    "2024-01-02": 612,
    "2024-01-03": 598
  }
}

GET

/api/v1/analytics/custom_domains/:uuid/total_pageviews_count

Total pageviews count

This endpoint returns the total number of pageviews for a custom domain.

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.

Request

GET

/api/v1/analytics/custom_domains/:uuid/total_pageviews_count

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/total_pageviews_count \
  -H "Authorization: Bearer {token}" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "count": 45678
}

GET

/api/v1/analytics/custom_domains/:uuid/pageviews_by_date

Pageviews by date

This endpoint returns the number of pageviews broken down by date.

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.
Name
frequency
Type
string
Description
Time grouping frequency (day, week, month). Default: day.

Request

GET

/api/v1/analytics/custom_domains/:uuid/pageviews_by_date

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/pageviews_by_date \
  -H "Authorization: Bearer {token}" \
  -d frequency="day" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "data": {
    "2024-01-01": 1523,
    "2024-01-02": 1612,
    "2024-01-03": 1598,
    "2024-01-04": 1687
  }
}

GET

/api/v1/analytics/custom_domains/:uuid/total_visits_count

Total visits count

This endpoint returns the total number of visits (sessions) for a custom domain. A visit is one visitor within one clock hour (UTC).

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.

Request

GET

/api/v1/analytics/custom_domains/:uuid/total_visits_count

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/total_visits_count \
  -H "Authorization: Bearer {token}" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "count": 25789
}

GET

/api/v1/analytics/custom_domains/:uuid/visits_by_date

Visits by date

This endpoint returns the number of visits (sessions) broken down by date. A visit is one visitor within one clock hour (UTC).

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.
Name
frequency
Type
string
Description
Time grouping frequency (day, week, month). Default: day.

Request

GET

/api/v1/analytics/custom_domains/:uuid/visits_by_date

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/visits_by_date \
  -H "Authorization: Bearer {token}" \
  -d frequency="day" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "data": {
    "2024-01-01": 823,
    "2024-01-02": 912,
    "2024-01-03": 878,
    "2024-01-04": 945
  }
}

GET

/api/v1/analytics/custom_domains/:uuid/pageviews_per_visit_by_date

Pageviews per visit by date

This endpoint returns the average number of pageviews per visit (session) broken down by date. This metric helps understand user engagement by showing how many pages users view in a single session.

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.
Name
frequency
Type
string
Description
Time grouping frequency (day, week, month). Default: day.

Request

GET

/api/v1/analytics/custom_domains/:uuid/pageviews_per_visit_by_date

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/pageviews_per_visit_by_date \
  -H "Authorization: Bearer {token}" \
  -d frequency="day" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "data": {
    "2024-01-01": 2.4,
    "2024-01-02": 2.7,
    "2024-01-03": 2.5,
    "2024-01-04": 2.8
  }
}

GET

/api/v1/analytics/custom_domains/:uuid/sources

Traffic sources

This endpoint returns the traffic sources for your custom domain, including referrers and their percentage distribution. count is the number of unique visitors. Visitors without a referrer are listed as Direct.

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.

Request

GET

/api/v1/analytics/custom_domains/:uuid/sources

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/sources \
  -H "Authorization: Bearer {token}" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "data": [
    {
        "name": "Direct",
        "count": 21344,
        "percentage": 83.94
    },
    {
        "name": "www.google.com",
        "count": 1835,
        "percentage": 7.22
    },
    // ... more sources
  ]
}

GET

/api/v1/analytics/custom_domains/:uuid/utm_params

UTM parameters

This endpoint returns the values of a UTM parameter in your traffic. count is the number of unique visitors.

Required attributes

Name
utm_param
Type
string
Description
The UTM parameter to analyze (utm_source, utm_medium, utm_campaign, utm_term, utm_content).

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format).
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format).

Request

GET

/api/v1/analytics/custom_domains/:uuid/utm_params

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/utm_params \
  -H "Authorization: Bearer {token}" \
  -d utm_param="source" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "data": [
    {
      "name": "newsletter",
      "count": 1234,
      "percentage": 58.48
    },
    {
      "name": "twitter",
      "count": 876,
      "percentage": 41.52
    }
  ]
}

GET

/api/v1/analytics/custom_domains/:uuid/pages

Pages

This endpoint returns the most viewed pages on your custom domain. count is the number of pageviews.

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.

Request

GET

/api/v1/analytics/custom_domains/:uuid/pages

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/pages \
  -H "Authorization: Bearer {token}" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "data": [
    {
      "name": "/",
      "count": 12345,
      "percentage": 44.66
    },
    {
      "name": "/blog",
      "count": 8765,
      "percentage": 31.71
    },
    {
      "name": "/pricing",
      "count": 6543,
      "percentage": 23.63
    }
  ]
}

GET

/api/v1/analytics/custom_domains/:uuid/locations

Locations

This endpoint returns geographic analytics data about your visitors, broken down by country, region, or city. count is the number of unique visitors. country_code is the ISO country code, also for regions and cities.

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.
Name
location_type
Type
string
Description
Type of location data to return (country, region, city). Default: country.

Request

GET

/api/v1/analytics/custom_domains/:uuid/locations

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/locations \
  -H "Authorization: Bearer {token}" \
  -d location_type="country" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "data": [
    {
      "name": "United States",
      "country_code": "US",
      "count": 45678,
      "percentage": 56.29
    },
    {
      "name": "United Kingdom",
      "country_code": "GB",
      "count": 23456,
      "percentage": 28.9
    },
    {
      "name": "Germany",
      "country_code": "DE",
      "count": 12345,
      "percentage": 15.21
    }
  ]
}

GET

/api/v1/analytics/custom_domains/:uuid/devices

Devices

This endpoint returns detailed analytics about the devices used to access your custom domain, broken down into three categories: browsers, operating systems, and screen sizes. count is the number of unique visitors.

Optional attributes

Name
from
Type
string
Description
Start date for the analytics period (ISO 8601 format). Defaults to 30 days ago.
Name
to
Type
string
Description
End date for the analytics period (ISO 8601 format). Defaults to current date.

Request

GET

/api/v1/analytics/custom_domains/:uuid/devices

curl -G https://app.saascustomdomains.com/api/v1/analytics/custom_domains/:uuid/devices \
  -H "Authorization: Bearer {token}" \
  -d from="2024-01-01" \
  -d to="2024-01-31"

Response

{
  "data": {
    "browsers": [
      {
        "name": "Chrome",
        "browser_id": "chrome",
        "count": 14510,
        "percentage": 50.39
      },
      {
        "name": "Firefox",
        "browser_id": "firefox",
        "count": 9703,
        "percentage": 33.7
      }
    ],
    "operating_systems": [
      {
        "name": "macOS",
        "operating_system_id": "mac",
        "count": 15528,
        "percentage": 53.93
      },
      {
        "name": "Windows",
        "operating_system_id": "windows",
        "count": 9481,
        "percentage": 32.93
      }
    ],
    "screen_sizes": [
      {
        "name": "Desktop",
        "screen_size_id": "desktop",
        "count": 26708,
        "percentage": 92.76
      },
      {
        "name": "Mobile",
        "screen_size_id": "mobile",
        "count": 1907,
        "percentage": 6.62
      }
    ]
  }
}