---
title: Common endpoints
description: 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](/docs/cloud/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](/docs/api-reference/list-websites) |
| Get a single website | `GET /websites/{websiteId}` | [Get a website](/docs/api-reference/get-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](/docs/api-reference/get-website-stats) |
| Visitors active in the last 5 minutes | `GET /websites/{websiteId}/active` | [Get active website visitors](/docs/api-reference/get-website-active) |

## Charts over time

| Task | Endpoint | Details |
| --- | --- | --- |
| Pageviews and sessions time series | `GET /websites/{websiteId}/pageviews` | [Get pageviews and sessions over time](/docs/api-reference/get-website-pageviews) |
| Events time series | `GET /websites/{websiteId}/events/series` | [Get custom event counts over time](/docs/api-reference/get-website-event-series) |

## 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](/docs/api-reference/get-website-metrics) |
| Same list with pageviews, visitors, visits, bounces, and time per row | `GET /websites/{websiteId}/metrics/expanded?type=path` | [Get detailed website metrics](/docs/api-reference/get-website-expanded-metrics) |

## Realtime

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

---

## 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:

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

```json
{ "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](/docs/cloud/api-key) the same
way: `Authorization: Bearer <api-key>`. See [Authentication](/docs/api/authentication).

**2. Find the website ID.**

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

```json
{
  "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:

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

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