Changelog

This changelog is generated automatically from GitHub Releases.

v0.6.25

2026-06-07 Β· GitHub

[0.6.25] - 2026-06-07

Added

Changed

  • validate_state error messages now mention set_cloud_api_key() alongside set_url_base() / login(). Same exception type (OperationNotAllowedError) and trigger conditions; text only.
  • Response models are more tolerant of variant/partial responses: WebsiteStats.comparison and Website.user are now optional, and Website accepts createUser (returned by team-website listings, where userId is null). Successful responses today are unaffected.
  • Internal: expanded the unit test suite (now 128 tests) following a suite review β€” added behavioral coverage for set_url_base validation, the validate_state guards, the login/login_async happy path and response-model deserialization (LoginResponse, WebsitesResponse), websites/websites_async, the disable() no-op (asserting no HTTP request is made), ip_address payload inclusion/omission, explicit-arg-overrides-defaults precedence, heartbeat_async self-hosted, and the verify_token/heartbeat failure branches. Added a sync/async parity harness and consolidated the per-file HTTP mock builders into a shared tests/_mocks.py (net ~210 fewer lines). No production behavior changed.

Fixed

  • website_stats_async() sent its date range as snake_case start_at/end_at query params, which the Umami API ignores β€” it silently returned all-time stats regardless of the requested window. Now sends camelCase startAt/endAt, matching the sync website_stats(). (#18)
  • active_users() and active_users_async() read the active-visitor count from a non-existent x key, so they always returned 0. They now read Umami’s current visitors key (falling back to the legacy x key for compatibility). (#19)
  • website_stats() / website_stats_async() sent their url and host filters under the old query-param names, which Umami renamed on 2025-10-07 (url β†’ path, host β†’ hostname) β€” so filtering stats by URL or hostname was a silent no-op. The public url/host keyword arguments are unchanged; they now map to the current path/hostname wire names. (#20)
  • heartbeat() / heartbeat_async() issued a POST to /api/heartbeat, which current Umami answers with 405 Method Not Allowed; the broad exception handler swallowed the error so the call always returned False even against a healthy server. They now issue a GET (the endpoint returns {"ok": true}).
  • new_event() and new_revenue_event() (sync) defaulted url to '/event-api-endpoint' while their async twins used '/'. All four now default to '/', so the sync/async twins agree and no placeholder path appears in dashboards.

v0.5.24

2026-06-04 Β· GitHub

[0.5.24] - 2026-06-04

Changed

  • Migrated HTTP backend from httpx to httpx2, imported as import httpx2 as httpx so all call sites remain unchanged
  • Files: umami/umami/impl/__init__.py, umami/requirements.txt, umami/pyproject.toml, pyrefly.toml, README.md, umami/README.md

v0.4.23

2026-03-13 Β· GitHub

[0.4.23]

Added

  • new_revenue_event() and new_revenue_event_async() for tracking revenue with Umami’s new revenue feature
  • Revenue events automatically inject revenue (float) and currency (ISO 4217 string) into event custom data
  • Input validation: revenue must be a number >= 0, currency must be a non-empty string
  • Defaults to event_name='revenue' and currency='USD' for simple usage
  • 15 new tests covering sync/async revenue events, validation, and edge cases

v0.3.22

2026-02-03 Β· GitHub

[0.3.22] - 2026-02-02

Fixed

  • new_event_async crashed with binascii.Error due to erroneous base64.b64decode / json.loads calls on the plain-JSON API response; now returns resp.json() directly, matching the other event and page-view methods

v0.3.21

2025-12-12 Β· GitHub

Added

  • Change-log preservation section for tracking historical release details
  • Pyrefly configuration file treating umami/umami package as type-resolution root

Changed

  • Centralized all version information into a single location for easier maintenance
  • Updated Python requirement to 3.10+ (dropped support for Python 3.8 and 3.9)
  • Refactored WebsiteStats to use plain integers instead of custom Metric type - Thanks @rubitcat (#15)
  • Updated ruff.toml to enforce consistent import ordering

Fixed

  • Suppressed and cleaned up unnecessary type-checking warnings

v0.2.20

2025-05-31 Β· GitHub

Umami-Python Release Notes

Since 5fa35183 (7 commits)

πŸš€ New Features

  • Development and Testing Tracking: Added options to disable tracking for development and testing environments. This allows users to control data collection based on their needs.

When tracking is disabled: - βœ… No HTTP requests are made to your Umami server - βœ… API calls still validate parameters (helps catch configuration issues) - βœ… All other functions work normally (login, websites, stats, etc.) - βœ… Functions return appropriate values for compatibility

πŸ“š Documentation

  • Documented the heartbeat check feature for monitoring system health.
  • Added documentation for new methods in the Umami API: get_heartbeat and enabled/disable.

🧹 Maintenance

  • Sorted some imports in various files to improve code organization and readability.
  • Fixed a minor typo in the documentation, ensuring consistency across the project.

v0.2.19

2025-05-31 Β· GitHub

Umami-Python Release Notes

Since 1d17c014 (16 commits)

πŸš€ New Features

πŸ› Bug Fixes

  • Login Fix: Corrected the API data handling from data to json in the login process. Originally, this was not a problem with the server, but it has started failing. If you have encountered login errors, this may fix it.

⚑ Performance

  • Heartbeat Function Optimization: Improved the performance of the heartbeat function by optimizing its execution flow.

v0.2.18

2025-05-31 Β· GitHub

Umami-Python Release Notes

Since 3a08f77a (2 commits)

πŸš€ New Features

  • Python Version Update: Upgraded to Python 3.13 and 3.14, providing better support for modern applications.

πŸ› Bug Fixes

  • API Call Method Fix: Corrected the use of data instead of json in login API calls, ensuring proper data transmission.

Originally, this was not a problem with the server, but it has started failing. If you have encountered login errors, this may fix it.

v0.2.17

2024-04-19 Β· GitHub

Adds is_logged_in() -> bool method to check whether login has been called and was successful.

v0.2.15

2024-03-01 Β· GitHub

  • Fixes schema change from Umami 2.9 to 2.10 on websites response
  • Includes new heartbeat function from 0.1.14 release

v0.1.14

2024-03-01 Β· GitHub

Add heartbeat API endpoint.

v0.1.13

2024-02-13 Β· GitHub

Support IP address in new_event and new_page_view payloads, see issue #2.

It looks like Umami added the IP data field in the payload (see https://github.com/umami-software/umami/pull/2479 ). It’s not clear when the feature will be released in a new build ( https://github.com/umami-software/umami/releases ). But in preparation, I added the id_address parameter to both new_event and new_page_view as well as their async twins.

This is out in version 0.1.13 and on PyPI at https://pypi.org/project/umami-analytics/0.1.13/ Thanks for the idea @ddxv

v0.1.12

2024-01-27 Β· GitHub

Add ability to pass alternative user agent to events (but be careful, umami blocks what it perceives as bots).

v0.1.11

2024-01-24 Β· GitHub

v0.1.10

2024-01-22 Β· GitHub

  • Added platform type (e.g. Windows) to user agent.
  • Added doc strings to most methods.
  • Bump the version for next release.
  • Added better validation for some functions.
  • Added custom error types for validation.

v0.1.9

2024-01-21 Β· GitHub

First real release outside our own apps. Enjoy!