# Umami

> Umami is an open source, privacy-first web analytics platform. It measures website
> traffic without cookies and without collecting personally identifying information,
> so it can run without a consent banner. It ships two ways: Umami Cloud (hosted,
> metered on events) and a self-hosted MIT-licensed application you run yourself.
> The API gives programmatic access to everything the dashboard shows — websites,
> sessions, events, metrics, reports, teams, links and pixels.

Generated by API Evangelist from https://github.com/api-evangelist/umami on 2026-08-13.
method: generated — Umami does not serve /llms.txt. It DOES serve the full corpus at
https://docs.umami.is/llms-full.txt (HTTP 200, ~350KB of clean markdown); only the
index variant that should point at it is missing (HTTP 404).

## Two surfaces, two credentials

Umami Cloud and self-hosted Umami are the same software with different front doors.
Do not mix them up — the base URL, the path prefix and the credential all differ.

- **Umami Cloud** — base `https://api.umami.is/v1`. Resource paths hang directly off
  it: `GET https://api.umami.is/v1/websites`. Authenticate with an API key created in
  the Cloud dashboard, sent as `Authorization: Bearer <api-key>`. Region can be pinned:
  `https://api.umami.is/v1/us` or `https://api.umami.is/v1/eu`, otherwise it defaults
  to the account's region.
- **Self-hosted** — base `http://<your-instance>/api`. Authenticate by POSTing
  username/password to `/api/auth/login` and sending the returned JWT as
  `Authorization: Bearer <token>`.
- **Collection** is a third, separate surface that takes NO credential. Umami Cloud
  ingest moved to `gateway.umami.is` on 2026-06-06.

API access is not available on the free Hobby plan. It starts at Pro ($20/month).

## Things that will bite you

- A **missing** credential returns **400** (`{"error":{"code":"bad-request"}}`), not 401.
  An **invalid** credential returns 401 (`{"error":{"code":"unauthorized"}}`).
- **50 calls per 15 seconds per API key**, flat across all plans. No rate-limit headers
  are returned, so you must pace yourself blind.
- **No idempotency key anywhere**, including on `POST /api/send` and `POST /api/batch`.
  A blind retry after a timeout double-counts events, and events are the billing unit.
- `POST /api/batch` returns **200 even when items fail**. Check
  `errors` and `details[]` in the body, not the status code.
- `startAt` / `endAt` are **UNIX milliseconds**. The `unit` parameter is **silently
  promoted** to a coarser bucket when the range exceeds its maximum — read the
  granularity you got back, don't assume it matches what you asked for.
- Umami Cloud **bars API keys** from `/me/password`, `/users` and `/users/*`.
- **Breaking changes land without notice.** There is no Sunset header, no deprecation
  window and no path aliasing. On 2025-10-07 six filter/report identifiers were renamed
  in one day inside `/v1`.
- Each stored **event data property counts as a billable event**, same as a pageview.

## API reference

- [Overview](https://docs.umami.is/docs/api)
- [Authentication (self-hosted)](https://docs.umami.is/docs/api/authentication): POST /api/auth/login, POST /api/auth/verify
- [API key (Cloud)](https://docs.umami.is/docs/cloud/api-key): creation, region pinning, 50/15s limit, barred routes
- [Websites](https://docs.umami.is/docs/api/websites): list, create, get, update, delete, reset, recorder config
- [Website statistics](https://docs.umami.is/docs/api/website-stats): stats, pageviews, metrics, metrics/expanded, active, daterange, events/series
- [Sessions](https://docs.umami.is/docs/api/sessions): sessions, sessions/stats, sessions/weekly, per-session activity and properties, session-data properties/values/stats/pivot
- [Events](https://docs.umami.is/docs/api/events): events, events/stats, event-data and its events/fields/properties/values/stats/pivot views
- [Reports](https://docs.umami.is/docs/api/reports): saved report CRUD plus ad-hoc execution of attribution, breakdown, funnel, goal, journey, performance, retention, revenue and utm
- [Realtime](https://docs.umami.is/docs/api/realtime): GET /api/realtime/:websiteId (always UTC)
- [Sending stats](https://docs.umami.is/docs/api/sending-stats): POST /api/send, POST /api/batch
- [Share](https://docs.umami.is/docs/api/share): share creation and revocation
- [Links](https://docs.umami.is/docs/api/links) and [Pixels](https://docs.umami.is/docs/api/pixels)
- [Teams](https://docs.umami.is/docs/api/teams), [Users](https://docs.umami.is/docs/api/users), [Me](https://docs.umami.is/docs/api/me), [Admin](https://docs.umami.is/docs/api/admin)
- [API client](https://docs.umami.is/docs/api/api-client) and [Node client](https://docs.umami.is/docs/api/node-client)

## Client libraries

- `@umami/api-client` — TypeScript client, one method per endpoint. Latest 0.80.0 (2025-07-25).
  Note: predates Umami v3 and does not cover the current API surface.
- `@umami/node` — server-side event collection. Latest 0.4.0 (2024-08-19).
- `@umami/components` — React components. Latest 0.131.0 (2026-02-16), undocumented.
- `@umami/cli` — 0.2.0 (2023-11-28). Abandoned; not referenced in the docs.

## Tracking and embedding

- [Tracker configuration](https://docs.umami.is/docs/tracker-configuration) — the script tag and its data-* attributes
- [Tracker functions](https://docs.umami.is/docs/tracker-functions) — umami.track(), umami.identify()
- [Track events](https://docs.umami.is/docs/track-events)
- [Embed analytics in your app](https://docs.umami.is/docs/guides/embed-analytics-in-your-app) — share-URL iframe, direct API, or the API client
- [Enable share URL](https://docs.umami.is/docs/enable-share-url) — anyone with the link can read the dashboard

## Operations and trust

- Pricing: https://umami.is/pricing — Hobby $0 (100K events, 1 site, 6mo retention, no API),
  Pro $20/mo (1M events, $0.00003 overage, API access), Business $200/mo (10M events,
  $0.00002 overage, Streaming API, replays, heatmaps), Enterprise custom (SAML SSO, SLA, audit log)
- Changelog: https://docs.umami.is/docs/cloud/changelog — dated, route-level, HTML only, no feed
- Status: https://umami.statuspage.io (machine-readable at /api/v2/status.json).
  Note `status.umami.is` does NOT resolve.
- Security: https://umami.is/security — vulnerability reports to security@umami.is.
  Umami states plainly it is NOT SOC 2 or ISO 27001 certified and has not completed an
  independent penetration test. GDPR/CCPA claimed; DPA public at https://umami.is/dpa.
- Source: https://github.com/umami-software/umami (MIT). Current release v3.3.0 (2026-08-12).

## Not available

Umami publishes no OpenAPI document, no AsyncAPI, no JSON Schema, no webhooks, no
first-party MCP server, no A2A agent card, no OAuth/OIDC, no scopes, and no
`/.well-known/` documents of any kind on any host.

## Optional

- [Full documentation corpus](https://docs.umami.is/llms-full.txt) — Umami's own complete docs as markdown
- [Metric definitions](https://docs.umami.is/docs/metric-definitions)
- [Automate reporting with the API](https://docs.umami.is/docs/guides/automate-reporting-with-api)
- [Self-hosting install](https://docs.umami.is/docs/install)
- [Environment variables](https://docs.umami.is/docs/environment-variables)