Get Website Stats — GET /api/websites/{websiteId}/stats

Retrieve pageviews, unique visitors, visits, bounces, and total time on site for any date range, with an optional comparison period for trend analysis.

Use this endpoint to pull the headline numbers shown on the Betterumami Overview screen: pageviews, unique visitors, visits, bounces, and total time on site. Supply a date range using Unix millisecond timestamps (startAt/endAt) or ISO 8601 strings (startDate/endDate). Add the compare parameter to get a parallel set of numbers for the previous period or the same period last year, making it easy to calculate percentage changes in your own dashboards.

GET /api/websites/{websiteId}/stats

Request

Headers

Authorization · string · required

Bearer token. Pass your API key: Authorization: Bearer <api-key>

Path Parameters

websiteId · string · required

The unique UUID of the website to query.

Query Parameters

Date Range

startAt · number

Start of the date range as a Unix timestamp in milliseconds. Use this or startDate.

endAt · number

End of the date range as a Unix timestamp in milliseconds. Use this or endDate.

startDate · string

Start of the date range as an ISO 8601 date or datetime, e.g. 2024-01-01 or 2024-01-01T00:00:00Z. Use this or startAt.

endDate · string

End of the date range as an ISO 8601 date or datetime. Use this or endAt.

timezone · string

IANA time zone used to interpret dates, e.g. America/New_York. Defaults to UTC.

unit · string

Time interval used to group results when computing statistics: minute, hour, day, month, or year.

compare · string

Include a comparison period in the response. prev compares against the immediately preceding period of the same length; yoy compares against the same period one year ago.

Filters

path · string

Filter results to a specific URL path, e.g. /blog/my-post.

referrer · string

Filter by referring URL.

title · string

Filter by page title.

query · string

Filter by URL query string.

os · string

Filter by visitor operating system, e.g. Windows, macOS.

browser · string

Filter by visitor browser, e.g. Chrome, Firefox.

device · string

Filter by device category: desktop, mobile, or tablet.

country · string

Filter by ISO 3166-1 alpha-2 country code, e.g. US, DE.

region · string

Filter by region or subdivision of the visitor.

city · string

Filter by visitor city.

language · string

Filter by the browser’s preferred language, e.g. en-US.

event · string

Filter by custom event name.

utmSource · string

Filter by UTM campaign source.

utmMedium · string

Filter by UTM campaign medium.

utmCampaign · string

Filter by UTM campaign name.

utmContent · string

Filter by UTM campaign content.

utmTerm · string

Filter by UTM campaign search term.

tag · string

Filter by a tag attached to tracked activity.

hostname · string

Filter by the hostname on which the activity occurred.

distinctId · string

Filter by a custom identifier assigned to the visitor.

eventType · integer

Filter by event type: 1 for pageviews, 2 for custom events.

excludeBounce · string

Set to any non-empty value to exclude single-pageview visits from the results.

segment · string

UUID of a saved segment to apply as a filter.

cohort · string

UUID of a saved cohort to filter visitors by.

match · string

Controls how multiple filters combine. all requires every filter to match (AND logic); any requires at least one to match (OR logic). Defaults to all.

Response

200 – Success

pageviews · number · required

Total number of pageviews in the selected period.

visitors · number · required

Number of unique visitors in the selected period.

visits · number · required

Total number of visits (sessions) in the selected period.

bounces · number · required

Number of visits where the visitor viewed only one page.

totaltime · number · required

Aggregate time visitors spent on the site, in seconds.

comparison · object · required

Present when compare is supplied. Contains the same five metrics for the comparison period.

comparison.pageviews · number

Pageviews during the comparison period.

comparison.visitors · number

Unique visitors during the comparison period.

comparison.visits · number

Visits during the comparison period.

comparison.bounces · number

Bounces during the comparison period.

comparison.totaltime · number

Total time on site during the comparison period, in seconds.

200 Response

{
  "pageviews": 15171,
  "visitors": 4415,
  "visits": 5680,
  "bounces": 3567,
  "totaltime": 809968,
  "comparison": {
    "pageviews": 38675,
    "visitors": 10568,
    "visits": 14595,
    "bounces": 9364,
    "totaltime": 2182387
  }
}

Code Sample

curl -X GET 'https://api.umami.is/v1/websites/b8d3a1f0-1c2d-4e5f-8a9b-0c1d2e3f4a5b/stats?startAt=1757376000000&endAt=1757462400000&compare=prev' \
  -H 'Authorization: Bearer <api-key>'