umami Release Notes

Umami v3.4.0 is here with new Annotations, MCP support, API key management, a typed API client, session property segments, and security, analytics, and UI improvements.

New features

Annotations

Add dated notes to your website charts to keep launches, campaigns, and other important events alongside your analytics.

• Chart markers for website annotations
• Create, edit, and delete annotations
• All-day and time-specific notes
• Annotation management and date picker improvements

Model Context Protocol (MCP)

Connect MCP-compatible assistants to Umami to explore your analytics with read-only tools.

• Tools for traffic, events, sessions, funnels, goals, journeys, retention, attribution, revenue, performance, segments, and annotations
• Remote HTTP endpoint and local stdio support through @umami/mcp
• API key authentication with existing user and team permissions
• Self-hosted endpoint disabled by default; set MCP_ENABLED=1 to enable /mcp

See the MCP setup guide for configuration and examples.

API keys and typed API client

• Create and revoke account API keys under Settings → API keys
• New @umami/api-client TypeScript package generated from Umami's OpenAPI contracts
• Typed request parameters and responses, structured errors, and ESM/CommonJS support
• Generated OpenAPI documentation with endpoint and field descriptions

Analytics APIs

• Website-scoped GET endpoints for analytics queries
• Dedicated saved funnel and goal resources and stats endpoints
• Separate performance stats, chart, and metrics datasets
• Dedicated UTM metrics endpoint
• Legacy report APIs preserved through compatibility handlers

See the report API migration guide for endpoint mappings and compatibility details.

Segments and tracking

• Save session property filters in segments and combine them with active filters. #4507
• Set a visitor identity through the tracker data-distinct-id attribute. #4421
• Added New Taiwan Dollar (TWD) and Icelandic Króna (ISK) revenue currencies. #4444 #4516
• Added Georgian and Azerbaijani translations. #4495 #4520

Security

• Reject partial 2FA tokens for authenticated API access
• Bind authenticated sessions to password fingerprints
• Exclude deleted teams from access checks and invalidate their join codes
• Prevent website reassignment when updating reports
• Added Gitleaks secret scanning and refreshed security dependency overrides

Migrations

This release includes schema migrations for annotations and API keys:

• prisma/migrations/25_add_annotation
• prisma/migrations/26_add_api_key

Migrations run automatically during the build process. Existing saved report definitions and IDs are retained by the analytics API changes.

Fixes

• PostgreSQL and ClickHouse timezone inconsistencies. #4541 #3810
• Identified visitors sharing an IP address and user agent now receive separate sessions by distinct ID
• PostgreSQL session activity queries use correlated EXISTS to improve query behavior. #4528
• Removed unnecessary sorting from PostgreSQL visitor count queries. #4523
• API client path parameter handling
• Commas in regular-expression filter values are preserved. #4496
• Filter values stay in sync when operators change
• Custom page selector values. #4490
• Wildcard controls in goal and funnel forms
• Creating a board without a description. #4469
• Board handling when a referenced website has been deleted
• Pasting one-time passwords on mobile. #4465
• Fullscreen date filter dropdown on mobile
• Manage teams navigation respects the configured base path. #4502
• Hidden sidebar scrollbar when collapsed. #4472
• Full path metric label tooltips. #4533
• Website selector behavior, event detail wrapping, and chart tooltip styling

Updates

• Next.js 16.3.4
• Prisma 7.10.0
• React 19.3.0
• React Zen component library upgrades and shared theme tokens
• Refined team navigation and top navigation selectors
• API integration coverage for PostgreSQL and ClickHouse
• OpenAPI and generated client validation in CI
• Runtime, frontend, build tooling, and security dependency updates

Thanks

@Alphapin @GroophyLifefor @JoeJoeflyn @MontejoJorge @bm1016bm-svg @brantsrasmus @dongwonmoon @flamelin @franciscao633 @jamalkamaladdin @justadityaraj @luca-seemann @lukkshh @nicolas2601

Full Changelog: v3.3.1...v3.4.0

Umami v3.3.1 is a maintenance release focused on safer upgrades, tracking correctness, analytics accuracy, and UI fixes.

Updates

• Hardened two-factor authentication when TWO_FACTOR_ENCRYPTION_KEY is missing or invalid, with safer API enforcement and clearer configuration feedback. #4443
• Preserved the root path when REMOVE_TRAILING_SLASH is enabled and reset tracker visit state when a session drifts. #4152
• Fixed event property filtering so fields and values respect the selected event name. #4461
• Preserved events without matching session records and stabilized relational event pagination. #4462
• Improved expanded metrics query performance and fixed funnel steps containing null event values.
• Preserved zero and false values in website value responses.
• Improved handling of username conflicts involving deleted users.
• Added broader coverage for 2FA status, setup, verification, disable, admin, team, and login flows.
• Preserved menu item actions in admin dropdowns. #4453
• Fixed expanded-menu spacing and realtime search bar styling.
• Added missing 2FA translations and polished Traditional Chinese 2FA copy.

Migrations

• Added prisma/migrations/24_lowercase_username to normalize usernames from pre-3.2 installations while safely handling conflicts with soft-deleted accounts.

Thanks

@nrps9909 @tomazic89 @NoiceHax

Full Changelog: v3.3.0...v3.3.1

Umami v3.3.0 is here with new Two-Factor Authentication, session identity stitching, property filtering, board cloning, sparklines, improved bounce detection, and a large set of security, performance, and UI fixes.

New features

Two-Factor Authentication (2FA)

Umami now supports TOTP-based two-factor authentication for self-hosted installs.

• 2FA setup with QR code and manual key entry
• Backup codes for account recovery
• 2FA step integrated into the login flow
• User security settings page
• Team-level 2FA enforcement settings
• Admin security settings and 2FA reset for users
• Rate limiting with 429 responses on repeated failed attempts
• Transactional backup code handling to prevent double-use race conditions

Session identity stitching

Sessions are now stitched together when a visitor is identified, giving you a complete view of activity across devices and visits.

• Identified sessions are linked for post-identify reads
• Linked ID displayed in the session profile
• Session delete feature for relational databases #2940
• Session modals use full-height layouts with improved mobile behavior

Session and event property filtering

Filter your data using session and event properties. #2945 #4008

• Property filters across session and event data views
• Unique session data entries enforced at the database level
• Duplicate data types resolved using dominant type logic
• Performance improvements for session activity queries

Board cloning

Boards can now be cloned, making it easy to duplicate and iterate on dashboards.

Sparklines

Website, Link, and Pixel tables now display sparklines for a quick visual overview of activity.

Tracking code workflow

Adding a new website now walks you through installing the tracking code.

Bounce detection

• Simplified bounce definition for SPA websites
• Optimized bounce detection queries

Tracker and API improvements

• Tracker build converted to TypeScript with published type definitions
• recorder.js CORS header support #4426
• Punycode domain support #2170
• Same-domain referrers are no longer saved and path-only referrers resolve correctly
• IRR (Iranian Rial) added to supported currencies
• Improved Persian (fa-IR) support and Hebrew RTL support
• Organic Facebook traffic channel attribution #4297
• Web app manifest fetched with credentials

Security

• Server-side validation for website name and domain input
• Hardened event data deletion #4435
• Hardened report references in boards
• Minimum 8-character slug enforced on share link create/update #4376
• Channel metrics literals escaped in queries
• Docker runtime image CVE fixes and bundled npm removed
• 2FA encryption key validation and transactional OTP handling

Migrations

This release includes schema migrations for session linking, 2FA, and session data:

• prisma/migrations/21_add_session_link
• prisma/migrations/22_add_2fa
• prisma/migrations/23_update_session_data

Migrations run automatically during the build process.

Fixes

• Funnel validation #4434
• Revenue query filtering #4286
• Board funnel and goal preview
• ComboBox and MultiSelect issues #4355
• Session modal issues on mobile #4358
• Session modals dismiss when clicking outside
• Dashboard empty-state Edit label
• formatLongNumber billions calculation
• Custom CLIENT_IP_HEADER not parsing x-forwarded-for chains
• GROUP BY error in event data queries on PostgreSQL
• Identified session ID generation
• Session 404 handling with added test coverage
• Heatmap and session replay mobile layouts #4417
• Heatmap iframe alignment and viewport clipping
• Website transfer state bug
• Dialog context error in language popover
• Docker ALLOWED_FRAME_URLS resolved from the runtime environment
• Docker server runs as PID 1 to drop idle launcher processes
• Website events query performance and activity search persistence
• Sidebar navigation accessibility and layout improvements
• Themed overlay scroll areas replacing global scrollbars
• Missing translations for Russian, Korean, Spanish, German, and European Portuguese

Updates

• Next.js 16.3.0
• Prisma 7.9.1
• React Zen component library upgrades
• Tracker type checking added to the build
• Runtime, frontend, and security dependency updates

Thanks

@boutterudy @Yashh56 @sushant-kataria @maxiride @Niki2k1 @mamal72 @m0sth8 @Sagittarius @luca-seemann @brantsrasmus @imparpaulo01 @sarmah-rup @rogerhmar @ShubhamPathak1 @leonacostaok @Kopaev @daeho-ro @PeterUstinox @Sebasmzt @sebiweise @anvme

Full Changelog: v3.2.0...v3.3.0

Umami v3.2.0 is here with new Heatmaps, improved properties reporting, better Session Replay controls, revenue report improvements, and a large set of security, performance, and UI fixes.

New features

Heatmaps

Heatmaps are now available as a first-class website report. Use click and scroll heatmaps to understand where visitors interact with each page, with overlays rendered from captured replay snapshots.

• Click and scroll heatmap reports
• Snapshot-based rendering with iframe previews
• Page path filtering
• Screen-width grouping for responsive layouts
• Depth labels and improved overlay scaling
• Self-hosted heatmap recording and storage support

Session Replay improvements

Session Replay received a round of reliability, filtering, and playback improvements.

• Replay filters for finding sessions faster
• Fragmented replay events are normalized for playback
• Full rrweb snapshots are handled as separate replay chunks
• Replay payloads are chunked and oversized payloads are rejected
• Replay events flush on pagehide with a shorter interval
• Mobile layout and modal styling improvements

Event and session property reporting

Property reports now support richer data types and reusable charting across both event data and session data.

• Event data filters for booleans, dates, and arrays
• Event data charts for arrays, booleans, dates, and numeric values
• Session data screens with filtering, pivot tables, and property charts
• Property filter UI shared across event and session data
• Query optimizations for session property filters

Revenue reporting

Revenue reports have been split into focused APIs and views for better performance and flexibility.

• Cumulative mode for revenue charts
• Separate revenue chart, metrics, stats, and session queries
• Revenue metrics table and metrics bar
• Improved realtime report UI

DataGrid and table improvements

• Manual table/card view toggle for DataGrid
• Sorting on non-analytics tables, including websites, boards, links, pixels, teams, and admin tables
• Horizontal scrolling for overflowing tables
• Stable event chart colors across date range changes
• Hidden events stay hidden when the date range changes

Tracker and API improvements

• data-auto-pageview tracker attribute to suppress SPA pageview tracking when auto-pageview is disabled
• Tracker click handling for annotated containers
• Graceful handling for invalid pushState URLs
• URL query values included in pages report display
• LLM channel logic
• URL pageview metric and expanded metric support
• Configurable internal API URL handling

Sharing

• Share page options for filtering and theme enforcement
• Share-token permissions for websites, boards, links, and pixels
• Board share entity authorization fixes
• Unrestricted access for share tokens without section flags

Security

• Invalidates authenticated sessions after password changes
• Sanitizes sensitive data in logs
• Hides internal Prisma and database errors from API responses
• Hardens analytics writes and avoids leaking internal server errors to clients
• Validates SSO redirect URLs before setting auth tokens
• Restricts team owner assignment to admins
• Enforces team role hierarchy on user updates and removals
• Fixes share token confusion vulnerabilities
• Tightens API access checks by website section and share permissions
• Sanitizes CSV exports against formula injection
• Limits batch API payloads to 500 items
• Uses authenticated Redis keys on logout

Migrations

This release includes schema migrations for Heatmaps and event/session data pivot support:

• prisma/migrations/20_add_heatmap

Migrations run automatically during the build process.

Fixes

• Retention report completeness
• Dashboard and Board editing in Firefox #4168
• Funnel alias issues #4144
• Ambiguous query errors #4176
• Username login case-insensitivity #3981
• Redirect logged-in users away from the login page
• Active users indicator realtime link
• Website selector dropdown limit increased from 10 to 100
• DataGrid pagination preserving query params
• Long URLs in Links table pushing action buttons off-screen
• Long distinct IDs in session info
• Invalid dates causing Firefox event chart errors
• NaN timestamps breaking event charts in Firefox
• Pages report url_query display
• Empty and null value handling
• Malformed client IP handling in /api/send
• Invalid IP and localhost lookup failures in location detection
• Channel metrics queries
• Column alias collisions in session filters
• Pie chart rendering without a default height
• Broken demo link in the README
• Missing translations and consistency updates across multiple locales
• Country and flag data updates

Updates

• Next.js 16.2.6
• Prisma 7.8.0
• Cypress and Jest test suites migrated to Playwright and Vitest
• GitHub workflows migrated to Blacksmith runners
• Runtime, frontend, and security dependency updates

Thanks

@nurlennart @IEBqp @Maxime-J @Karthited @Nirator78 @manuelfesantos @JLUpengjiaji @yhyasyrian @tairosonloa @c0ball @anvme @yancat160 @seojcarlos @God-2077 @sputnik-mac @avasis-ai @SAYOUNCDR @nielskaspers @AymanAlSuleihi @gputier @ElfenB @ip00 @swayam-mishra @mturac @KadirFiratFTW @Kyzenkms

Full Changelog: v3.1.0...v3.2.0

Umami v3.1.0 is here with a ton of new features, including the much-anticipated Boards and Session Replay. This release also brings Web Vitals performance tracking, a redesigned share page, and hundreds of fixes and improvements.

New features

Boards

Boards are here! Create your own custom dashboards by composing components on a flexible row/column canvas. Pick from charts, tables, and metric components, bind them to any website, and share the finished board with your team.

• Row/column layout editor with resize, reorder, and remove controls
• Per-component website binding and live preview
• Free-form TextBlock components for notes and section headers
• Board sharing, duplication, and table-level edit/delete actions
• Dashboard-wide date range and filter controls

Session Replay

Watch real user sessions replayed in the browser. Session Replay is built on rrweb and works alongside your existing tracker.

• Configurable masking levels for privacy (defaults to moderate)
• Per-visit recording so replays stay short and focused
• Filterable replays table with event-level filtering
• Replay modal with mobile-friendly playback

Web Vitals performance tracking

Track Core Web Vitals (LCP, INP, CLS, FCP, TTFB) from your visitors' browsers. The redesigned Performance page shows industry-standard calculations with rating badges for each metric.

Redesigned share page

Share pages have a fresh look with full mobile support, a collapsible sidenav, and per-share display options. You can now:

• Name each share link
• Choose which sections visitors can see (overview, events, etc.)
• Apply filtered navigation so visitors only see what you want

Filters, segments, and cohorts

• OR logic across filters, segments, and cohorts
• Regex operators for more powerful matching
• Multiselect on equals/not-equals operators
• UTM filters and fields exposed throughout the app
• Exclude bounces toggle with filter-form integration

Funnels

• Per-step event property filters in both funnel creation and overview
• Wildcard support in the goals report

Other improvements

• Custom slug support for Links
• Pixel and Link detail pages with sharing
• MetricsBar added to the Events page
• Event type filter on Journeys
• Time unit selector (hour/day/month)
• Distinct ID available as a filter and metric dimension
• Cache-control headers on GET responses
• SKIP_BUILD_GEO env variable to skip geo DB build
• Configurable salt rotation period via env vars
• EdgeOne geolocation headers
• Version endpoint and settings display
• Download for breakdown reports
• Pagination limit on event charts, metrics tables, and UTM reports

Admin & internationalization

• Migrated from react-intl to next-intl with all 51 locale files translated
• Adopted the react-zen design system across the app
• Consolidated top navigation with embedded selectors for websites, boards, links, and pixels
• Team validation and redirect for invalid teams
• Team-gated feature resolution via Redis

Security

• Fixed IDOR vulnerabilities in reports and segments
• Blocked share tokens from all editing permissions and API modifications
• Restricted x-umami-client-* headers to cloud mode
• Various dependency vulnerability fixes (tar, ajv, jws, brace-expansion, next)

Migrations

This release includes schema migrations for Boards, Shares, Session Replay, and board duplicate-key handling. Migrations run automatically during the build process.

Fixes

• PostgreSQL 12/13 syntax error in Journeys #3970
• Implicit alias syntax error in Postgres session and event queries #4147
• name alias compatibility for Postgres 12 relational queries #3970
• Table alias missing in filterQuery #3869
• Timezone not applied to relational queries #3975
• Revenue chart timezone mismatch #4107
• Ambiguous session_id errors in SQL queries
• Breakdown alias column not found
• www. prefix not stripped during hostname comparison #3256
• Minute label formatting #3088
• Website select page size limited to 10 #3913
• Deleted website visibility #3865
• BASE_PATH support #4064
• Pixel event tracking #4028
• Pagination issues #4029
• Login email case-sensitivity #3981
• Tracker double-initialization when script injected more than once
• Tracker fetch priority now set to low #3642
• robots.txt fixes #3996
• Goals wildcard support #4086
• MetricsBar on Events page #3830
• Distinct ID in filters / expanded metrics #3861
• Team admin workflow for team members #2767
• Event type filter for Journeys #2803
• Salt rotation configurable via env #3427
• Share token allowing access to pages with undefined share params
• Fix #4058 (pixel tracking null referrer)
• Autofill background color in forms
• Denied storage access in tracker
• Prisma session race condition
• Docker Prisma migrate and stray query log
• Monthly truncation timezone issue
• Share page retention and logo margins
• Filters persisting across website change
• "All time" filter on websites with no data
• Japanese translation for "breakdown" label
• UAE emirate names in iso-3166-2.json
• IPv6 handling for client IP detection
• Numerous mobile UI fixes across admin, nav, share, and team screens

Updates

• Next.js 16.2.4
• Prisma 7.6.0
• Minimum Node.js version bumped to 22 (Prisma 7 requirement)

Thanks

@Yashh56 @boutterudy @AymanAlSuleihi @juanisidoro @cryst-hq @RaenonX @PaiJi @Gouttfi @AlejandroGispert @lawrence3699 @kkhys @journry789 @sputnik-mac @sbozh @Mintimate @Mravuri96 @maphubs @maennenajere @XahidEx @IndraGunawan @GochoMugo @FEgor04 @Nayrode @diogotcorreia @dyanakiev @fauzora @BrentRobert @hilja

This is a patch release to address the Next.js CVE and fixes many bugs.

Fixes

• Nextjs/RSC critical vulnerability #3829
• Time range selection back and forward arrows not jumping with correct steps #3828
• Links and Pixels are prefetched on dashboard #3814
• In the chart legend, when the URL is too long, the legend extends beyond the container boundaries, disrupting the page layout. #3813
• User is not able to switch back to My Account after switching to the Team #3802
• Reset of website stats is not possible after entries in Revenue table #3798
• Team workspace is not selectable after login #3796
• Error with long UTM parameters and click IDs #3790
• Direct visitors are missing on Channels (3.0.1) #3789
• "Last seen" - "First seen" fields broken since 3.0.1 #3775
• Tests are failing in 3.0.1 #3773
• Revenue sums not showing in 3.0.1 #3769
• Read-only prevents user from joining team #3764
• Regression: URL theme and lang parameters no longer work for public share links #3754

Updates

• Next.js 15.5.7
• Prisma 6.19.0

Thanks

@Lokimorty @imsyedabdullah @RaenonX @IndraGunawan