API

Common endpoints

The API exposes an operation for everything you can do in the app, but most integrations only touch a handful of read endpoints — the ones that power the website Overview screen. This page is a shortcut to those. Each row links to its full reference page for parameters and responses.

All paths below are relative to your API base URL: http://<your-umami-instance>/api when self-hosting, or the Umami Cloud base URL from your API key.

Find your website#

Most stats endpoints need a websiteId.

Task	Endpoint	Details
List every website you can access	`GET /api/websites`	List websites
Get a single website	`GET /api/websites/{websiteId}`	Get a website

Overview numbers#

The stat cards and active-visitor count at the top of the dashboard.

Task	Endpoint	Details
Pageviews, visitors, visits, bounces, total time (with comparison)	`GET /api/websites/{websiteId}/stats`	Get website summary statistics
Visitors active in the last 5 minutes	`GET /api/websites/{websiteId}/active`	Get active website visitors

Charts over time#

Task	Endpoint	Details
Pageviews and sessions time series	`GET /api/websites/{websiteId}/pageviews`	Get pageviews and sessions over time
Events time series	`GET /api/websites/{websiteId}/events/series`	Get custom event counts over time

Breakdowns#

Ranked lists for a single dimension — top pages, referrers, browsers, countries, events, and so on. Pass the dimension with type (path, referrer, browser, os, device, country, event, …).

Task	Endpoint	Details
Ranked list of one dimension	`GET /api/websites/{websiteId}/metrics?type=path`	Get ranked website metrics
Same list with pageviews, visitors, visits, bounces, and time per row	`GET /api/websites/{websiteId}/metrics/expanded?type=path`	Get detailed website metrics

Realtime#

Task	Endpoint	Details
Live countries, URLs, referrers, events, and totals (last 30 minutes)	`GET /api/realtime/{websiteId}`	Get real-time website activity

Working example#

Pull website summary statistics for one website over a 24-hour window.

1. Authenticate. On self-hosted Umami, exchange your credentials for a token:

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your-username", "password": "your-password"}'

{ "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A", "user": { "...": "..." } }

Send that token as Authorization: Bearer <token> on every request below. On Umami Cloud, skip this step and pass your API key the same way: Authorization: Bearer <api-key>. See Authentication.

2. Find the website ID.

curl http://localhost:3000/api/websites \
  -H "Authorization: Bearer <token>"

{
  "data": [
    { "id": "b8d3a1f0-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "name": "Example", "domain": "example.com" }
  ],
  "count": 1
}

3. Get the overview stats. startAt and endAt are millisecond epoch timestamps bounding the range — the example values below span a 24-hour window:

curl "http://localhost:3000/api/websites/b8d3a1f0-1c2d-4e5f-8a9b-0c1d2e3f4a5b/stats?startAt=1757376000000&endAt=1757462400000" \
  -H "Authorization: Bearer <token>"

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

PreviousSending stats NextChange my password