API

Common endpoints

A shortcut to the Umami API endpoints most integrations use, from listing websites to stats, time series, breakdowns, and realtime data.

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 https://api.umami.is/v1 on Umami Cloud with an API key. For example, GET /websites is http://<your-umami-instance>/api/websites or https://api.umami.is/v1/websites.

Find your website#

Most stats endpoints need a websiteId.

Task	Endpoint	Details
List your websites (add `includeTeams=true` to include team websites)	`GET /websites`	List websites
Get a single website	`GET /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 /websites/{websiteId}/stats`	Get website summary statistics
Visitors active in the last 5 minutes	`GET /websites/{websiteId}/active`	Get active website visitors

Charts over time#

Task	Endpoint	Details
Pageviews and sessions time series	`GET /websites/{websiteId}/pageviews`	Get pageviews and sessions over time
Events time series	`GET /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 /websites/{websiteId}/metrics?type=path`	Get ranked website metrics
Same list with pageviews, visitors, visits, bounces, and time per row	`GET /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 /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,
  "page": 1,
  "pageSize": 20
}

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