Skip to main content
GET
/
api
/
websites
/
:id
/
metrics
Get Metrics Breakdown
curl --request GET \
  --url https://api.example.com/api/websites/:id/metrics
{
  "data": {
    "type": "<string>",
    "rows": [
      {
        "value": "<string>",
        "visitors": 123,
        "pageviews": 123,
        "bounce_rate": 123,
        "avg_duration_seconds": 123,
        "prev_visitors": 123,
        "prev_pageviews": 123,
        "delta_visitors_abs": 123,
        "delta_visitors_pct": 123
      }
    ]
  },
  "pagination": {
    "total": 123,
    "limit": 123,
    "offset": 123,
    "has_more": true
  },
  "compare": {
    "mode": "<string>",
    "primary_range": [
      {}
    ],
    "comparison_range": [
      {}
    ]
  }
}

​
Path Parameters

​
id
string
required
Website ID

​
Query Parameters

​
type
string
required
The metric dimension to break down. Valid values:
  • page - Top pages by traffic
  • referrer - Top referrer domains
  • country - Traffic by country
  • region - Traffic by region/state
  • city - Traffic by city
  • browser - Browser breakdown
  • os - Operating system breakdown
  • device - Device type breakdown
  • language - Browser language breakdown
  • utm_source - UTM source parameter
  • utm_medium - UTM medium parameter
  • utm_campaign - UTM campaign parameter
  • hostname - Hostname breakdown
​
limit
integer
default:"10"
Number of results to return (1-100).
​
offset
integer
default:"0"
Number of results to skip for pagination.
​
start_date
string
Start date in YYYY-MM-DD format. Defaults to 6 days ago if not provided.
​
end_date
string
End date in YYYY-MM-DD format. Defaults to today if not provided.
​
timezone
string
IANA timezone string (e.g., America/New_York). Defaults to UTC.
​
include_bots
boolean
Whether to include bot traffic in results. Defaults to website’s bot policy setting.

​
Comparison Parameters

​
compare_mode
string
Comparison mode: none, previous_period, previous_year, or custom.
​
compare_start_date
string
Custom comparison start date (required when compare_mode=custom).
​
compare_end_date
string
Custom comparison end date (required when compare_mode=custom).

​
Filter Parameters

​
filter_country
string
ISO 3166-1 alpha-2 country code.
​
filter_page
string
Filter by page URL path.
​
filter_referrer
string
Filter by referrer domain.
​
filter_browser
string
Filter by browser name.
​
filter_os
string
Filter by operating system.
​
filter_device
string
Filter by device type.
​
filter_language
string
Filter by browser language.
​
filter_utm_source
string
Filter by UTM source parameter.
​
filter_utm_medium
string
Filter by UTM medium parameter.
​
filter_utm_campaign
string
Filter by UTM campaign parameter.
​
filter_region
string
Filter by geographic region/state.
​
filter_city
string
Filter by city name.
​
filter_hostname
string
Filter by hostname.

​
Response

​
data
object
Metrics breakdown data.
​
type
string
The metric type that was requested.
​
rows
array
Array of metric rows, sorted by visitors descending.
​
value
string
The dimension value (e.g., page URL, country code, browser name).
​
visitors
integer
Number of unique visitors for this value.
​
pageviews
integer
Number of pageviews for this value.
​
bounce_rate
number
Bounce rate percentage (0-100) for sessions involving this dimension value.
​
avg_duration_seconds
number
Average session duration in seconds for sessions involving this value.
​
prev_visitors
integer
Previous period visitors (only present when compare_mode is set).
​
prev_pageviews
integer
Previous period pageviews (only present when compare_mode is set).
​
delta_visitors_abs
integer
Absolute change in visitors (only present when compare_mode is set).
​
delta_visitors_pct
number
Percentage change in visitors (only present when compare_mode is set).
​
pagination
object
Pagination metadata.
​
total
integer
Total number of unique dimension values.
​
limit
integer
The limit used for this request.
​
offset
integer
The offset used for this request.
​
has_more
boolean
Whether there are more results available.
​
compare
object
Comparison metadata (only present when compare_mode is set).
​
mode
string
The comparison mode used.
​
primary_range
array
Two-element array with start and end dates of the primary period.
​
comparison_range
array
Two-element array with start and end dates of the comparison period.

​
Example Request

curl -X GET "https://analytics.example.com/api/websites/abc123/metrics?type=page&limit=10&start_date=2024-03-01&end_date=2024-03-07" \
  -H "Authorization: Bearer spk_live_your_api_key"

​
Example Response

{
  "data": {
    "type": "page",
    "rows": [
      {
        "value": "/",
        "visitors": 2341,
        "pageviews": 3892,
        "bounce_rate": 38.2,
        "avg_duration_seconds": 145.3
      },
      {
        "value": "/pricing",
        "visitors": 1823,
        "pageviews": 2104,
        "bounce_rate": 42.1,
        "avg_duration_seconds": 98.7
      },
      {
        "value": "/features",
        "visitors": 1542,
        "pageviews": 1876,
        "bounce_rate": 35.6,
        "avg_duration_seconds": 132.4
      },
      {
        "value": "/docs",
        "visitors": 1203,
        "pageviews": 4521,
        "bounce_rate": 28.9,
        "avg_duration_seconds": 287.1
      },
      {
        "value": "/blog/getting-started",
        "visitors": 891,
        "pageviews": 1012,
        "bounce_rate": 51.3,
        "avg_duration_seconds": 76.5
      }
    ]
  },
  "pagination": {
    "total": 124,
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "compare": null
}

​
Example with Comparison

curl -X GET "https://analytics.example.com/api/websites/abc123/metrics?type=country&limit=5&start_date=2024-03-01&end_date=2024-03-07&compare_mode=previous_period" \
  -H "Authorization: Bearer spk_live_your_api_key"

{
  "data": {
    "type": "country",
    "rows": [
      {
        "value": "US",
        "visitors": 1823,
        "pageviews": 4521,
        "bounce_rate": 41.2,
        "avg_duration_seconds": 125.3,
        "prev_visitors": 1542,
        "prev_pageviews": 3891,
        "delta_visitors_abs": 281,
        "delta_visitors_pct": 18.2
      },
      {
        "value": "GB",
        "visitors": 891,
        "pageviews": 2103,
        "bounce_rate": 38.7,
        "avg_duration_seconds": 142.1,
        "prev_visitors": 923,
        "prev_pageviews": 2234,
        "delta_visitors_abs": -32,
        "delta_visitors_pct": -3.5
      },
      {
        "value": "DE",
        "visitors": 723,
        "pageviews": 1654,
        "bounce_rate": 43.1,
        "avg_duration_seconds": 108.9,
        "prev_visitors": 651,
        "prev_pageviews": 1502,
        "delta_visitors_abs": 72,
        "delta_visitors_pct": 11.1
      }
    ]
  },
  "pagination": {
    "total": 47,
    "limit": 5,
    "offset": 0,
    "has_more": true
  },
  "compare": {
    "mode": "previous_period",
    "primary_range": ["2024-03-01", "2024-03-07"],
    "comparison_range": ["2024-02-23", "2024-02-29"]
  }
}

​
Notes

  • Valid metric types are defined in VALID_METRIC_TYPES constant in the backend
  • Results are always sorted by visitors in descending order
  • The limit parameter is clamped to 1-100
  • Use offset for pagination to retrieve additional results
  • Comparison fields (prev_*, delta_*) are only included when compare_mode is set

Build docs developers (and LLMs) love

Get started for freeTalk to us