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.

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 counted as a sequence of pageviews from the same user within a 30-minute window.

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 counted as a sequence of pageviews from the same user within a 30-minute window.

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.

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 analytics data for UTM parameters in your traffic.

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": [
    {
      "value": "newsletter",
      "count": 1234,
      "percentage": 45.2
    },
    {
      "value": "twitter",
      "count": 876,
      "percentage": 32.1
    }
  ]
}

GET

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

Pages

This endpoint returns analytics data for the most visited pages on your custom domain, including page paths and visit counts.

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": [
    {
      "path": "/",
      "views": 12345,
      "percentage": 25.4
    },
    {
      "path": "/blog",
      "views": 8765,
      "percentage": 18.2
    },
    {
      "path": "/pricing",
      "views": 6543,
      "percentage": 13.5
    }
  ]
}

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.

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": [
    {
      "location": "United States",
      "code": "US",
      "visitors": 45678,
      "percentage": 35.2
    },
    {
      "location": "United Kingdom",
      "code": "GB",
      "visitors": 23456,
      "percentage": 18.1
    },
    {
      "location": "Germany",
      "code": "DE",
      "visitors": 12345,
      "percentage": 9.5
    }
  ]
}

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.

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